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JSON at Work 


涵盖 JSON 基 础 知识 、 操 作 实 践 与 案例 
全 面 掌握 JSON 强 大 功能 的 明智 之 选 
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毕业 于 浙江 大 学 生物 科学 系 ， 热 衷 于 提 
升 产 品 的 用 户 体验 ， 在 UI 技术 领域 历经 
Java Swing、Adobe Flex， 终 至 Web 前 
端 。 目 前 主要 感 兴趣 的 领域 为 物 联网 ， 
并 致力 于 相关 产品 Uniboard 的 设计 开 
发 。 
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图 灵 社 区 的 电子 书 没有 采用 专 有 客 
户 端 ， 您 可 以 在 任意 设备 上 ， 用 自 
己 喜 欢 的 浏览 器 和 PDF 阅读 器 进行 
阅读 。 

但 您 购买 的 电子 书 仅 供 您 个 人 使 用 ， 
未 经 授权 ， 不 得 进行 传播 。 

我 们 愿意 相信 读者 具有 这 样 的 良知 
和 觉悟 ， 与 我 们 共同 保护 知识 产权 。 


如 果 购 买 者 有 侵权 行为 ， 我 们 可 能 
对 该 用 户 实 施 包括 但 不 限于 关闭 该 
帐号 等 维权 措施 ， 并 可 能 追究 法 律 
责任 。 
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内 容 提 要 


本 书 来 自 于 作者 实际 使 用 JSON 的 经 验 所 得 ， 主 要 内 容 包 括 JSON 基础 知识 ， 对 JSON 数据 
建 模 ， 在 Node.js, Ruby on Rails 和 Java 中 使 用 JSON， 结 构 化 JSON 文档 并 设计 测试 API， 搜 索 
JSON 文档 的 内 容 ， 将 ISON 文档 转换 成 其 他 数据 格式 ， 将 ISON 作为 企业 级 架构 中 的 一 部 分 来 
使 用 ， 等 等 。 

本 书 适合 对 Web 和 移动 端 应 用 、RESTful API 以 及 消息 系统 进行 设计 或 实现 的 架构 师 和 开 
BA ABI. 
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JavaScript 对 象 表示 法 (JavaScript Object Notation, JSON) 已 经 成 为 RESTful 接口 设计 中 
的 事实 标准 ， 架 构 师 和 开发 人 员 可 以 使 用 一 整套 现成 的 技术 生态 系统 〈( 鲜 为 人 知 的 标准 、 
工具 和 相关 技术 ) 来 搭建 设计 精巧 的 应 用 程序 。JSON 不 仅仅 是 Ajax 调用 中 XML 的 一 个 
简单 禁 代 品 ， 它 也 正 日 益 成 为 互联 网 数据 交换 领域 的 骨干 元 素 。 严 谨 的 标准 和 技术 最 佳 实 
践 加 上 对 JSON 的 热爱 ， 有 助 于 我 们 搭建 一 个 真正 优雅 、 有 用 而 又 高 效 的 应 用 程序 。 


唯一 的 缺憾 是 ， 没 有 一 本 书 将 这 一 切 串 连 起 来 进行 介绍 。 本 书 则 在 帮助 开发 人 员 使 用 
JSON， 以 搭建 企业 级 的 应 用 程序 与 服务 。 我 们 的 目标 是 促进 JSON 工具 的 使 用 ， 同 时 力图 
让 消息 /文档 设计 这 一 理念 在 日 新 月 异 的 API 社区 中 成 为 “一 等 公民 ”。 


我 和 JSON 的 接触 始 于 2007 年 ， 当 时 我 正在 负责 一 个 大 型 的 Web 门户 项 目 ， 而 该 项 目 
要 求实 现 拥 有 几 千 个 选项 的 下 拉 列 表 。 那 时 我 刚好 在 阅读 Rebecca Riordan 所 著 的 《Head 
First Ajax (中 文 版 )》， 因 此 设计 了 比较 优雅 的 架构 方案 。Ajax 能 够 解决 延迟 和 页 面 加载 问 
题 ， 但 是 该 如 何 处 理 数 据 呢 ? 前 几 年 我 一 直 在 使 用 XML 技术 而 且 很 成 功 ， 但 对 于 将 数据 
从 Web 应 用 程序 后 端 传输 到 前 端 展现 层 这 样 的 任务 ， 继 续 使 用 XML 技术 显得 有 些 大 炮 打 
蚊子 。《Head First Ajax (中 文 版 )》 中 提 到 了 名 为 ISON 的 一 种 新 数据 格式 ， 而 这 一 策略 
看 上 去 似乎 是 可 行 的 。 我 的 整个 团队 开始 研究 能 将 Java 对 象 转换 为 JSON 的 API， 并 最 终 
选择 了 JUnit 测试 程序 最 简短 的 方案 ， 我 们 的 目标 是 在 代码 有 效 的 前 提 下 ， 尽 可 能 简化 所 
需 的 工作 。 我 们 对 完成 后 的 应 用 程序 执行 了 严格 的 压力 测试 ， 而 从 Java 转换 为 JSON 的 操 
作 在 测试 中 从 未 成 为 性 能 瓶颈 。 最 终 ， 这 一 应 用 程序 在 生产 环境 中 呈现 出 了 很 好 的 可 扩展 
性 ， 用 户 也 能 瞬间 看 到 下 拉 列 表 。 


之 后 的 一 段 时 间 里 ， 我 思考 过 在 Web 应 用 程序 、RESTful API 和 消息 系统 中 均 使 用 JSON。 
2009 年 ， 因 为 XML Schema 可 以 在 数据 交换 过 程 中 提供 语义 校 验 ， 所 以 我 仍旧 在 项 目 中 使 
用 XML。 当时 我 的 技术 决策 是 这 样 的 : 在 Web 用 户 界面 上 使 用 JSON (出 于 速度 考虑 )， 
在 Web Service 和 消息 系统 中 则 使 用 XML (出 于 数据 集成 考虑 )。 不 过 ， 当 2010 年 听 说 
JSON Schema 后 ， 我 就 意识 到 自己 已 经 不 再 需要 XML 了 。JSON Schema 标准 目前 还 在 完 
善 中 ， 但 已 经 足够 成 熟 ， 足 以 用 于 企业 级 应 用 程序 中 的 数据 集成 任务 。 


时 至 今日 ， 我 已 经 习惯 ， 或 者 更 准确 地 说 ， 迷 上 了 JSON。 我 开始 在 网 络 上 搜索 ISON 的 
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其 他 功能 ， 并 发 现 了 大 量 的 API、 在 线 工 具 、 内 容 搜索 功能 等 。 简 而 言 之 ， 能 够 使 用 XML 
实现 的 功能 都 可 以 (也 应 当 ) JH ISON 实现 。 


之 后 我 开始 搜索 有 关 ISON 的 图 书 ， 却 失望 地 发 现 只 能 在 讲述 JavaScript 或 者 RESTful 
Web Service 的 书 中 ， 零 星 地 找到 一 两 章 有 关 ISON WAZA. JSON 社区 欣欣 向 荣 ， 拥 有 大 
量 的 支持 工具 、 文 章 和 博客 ， 但 除了 Douglas Crockford 的 JSON 官方 网 站 ， 尚 没有 一 处 地 
方 对 这 些 知识 和 资源 进行 汇聚 。 


本 书 的 目标 读者 


本 书 的 目标 读者 是 设计 或 实现 Web 和 移动 端 应 用 程序 、RESTful API 以 及 消息 系统 的 架构 
师 和 开发 人 员 。 本 书 中 的 代码 示例 是 用 以 下 编程 语言 编写 的 : JavaScript, Node.js, Ruby 
on Rails 和 Java。 如 果 你 使 用 的 是 其 他 编程 语言 ， 如 Groovy, Go, Scala, Perl, Python, 
Clojure 或 者 C#， 同 样 需 要 阅读 本 书 中 的 示例 代码 。 不 过 你 大 可 放心 ， 绝 大 多 数 主流 的 现 
代 编 程 语言 都 可 以 提供 优秀 的 JSON 支持 。 对 于 架构 师 ， 本 书 提供 了 指南 、 最 佳 实践 以 及 
架构 和 设计 图 表 。 然 而 ， 除 了 提供 技术 愿景 ， 真 正 的 架构 师 往 往 会 用 实际 代码 来 佐证 自己 
的 观点 。 虽 然 我 很 喜欢 编写 代码 来 使 用 JSON， 但 如 果 没 有 用 例 ， 缺 少 业务 和 技术 背景 ， 
那么 一 切 都 将 癌 无 意义 。 对 于 开发 人 员 ， 本 书 汇聚 了 代码 示例 、 工 具 、 单 元 测试 ， 等 等 。 


为 了 保持 简洁 和 专注 ， 第 5-10 章 仅 提 供 在 Node.js 中 编写 的 代码 示例 。 但 是 ， 将 这 些 示例 
转换 为 你 使 用 的 编程 语言 的 代码 并 不 难 。 


£6 rzi1 Be ^ ` 
实战 ”的 含义 
2000 年 年 中 ， 当 我 与 Scott Davis 合作 编写 JBoss at Work tt, RTE cA Zi BAIR 
人 员 能 在 日 常 工作 中 使 用 的 书 。 同 样 ， 本 书 的 目的 也 是 为 开发 人 员 提 供 实用 示例 ， 这 些 示 
例 是 我 根据 实际 的 ISON 使 用 经 验 所 编写 的 。 为 此 ， 我 在 每 章 后 面 添加 了 单元 测试 (如果 
这 一 章 的 内 容 可 以 编写 单元 测试 的 话 )。 原 因 很 简单 :如 果 一 段 代码 没有 对 应 的 测试 ， 则 
该 段 代码 不 存在 。 
准备 好 卷 起 袖子 看 代码 吧 。 无 论 你 是 架构 师 还 是 开发 人 员 ， 本 书 都 会 对 你 的 工作 有 所 帮助 。 


本 书 内 容 


通过 阅读 本 书 并 练习 书 中 的 示例 ， 你 将 学 到 以 下 实战 操作 : 

。 JSON 基础 知识 ， 以 及 如 何 对 ISON 数据 进行 建 模 ， 

。 {Æ Node.js, Ruby on Rails 以 及 Java 中 使 用 ISON; 

。 使 用 JSON Schema 结构 化 JSON 文档 来 设计 并 测试 API, 
。 EH JSON 搜索 工具 来 搜索 ISON 文档 的 内 容 ; 

。 (EH JSON 转换 工具 将 ISON 文档 转换 成 其 他 数据 格式 ; 

。 ISON 作为 企业 级 架构 中 的 一 部 分 来 使 用 ; 

。 比较 HAL, json:api 等 JSON 超 媒 体格 式 ; 
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。 使 用 MongoDB 来 存储 和 访问 ISON 文档 ， 
。 使 用 Apache Kafka 在 服务 间 交 换 JSON 消息 ; 
。 使 用 免费 的 ISON 工具 来 简化 测试 ; 

通过 简单 的 工具 和 类 库 ， 使 用 自己 偏好 的 编程 语言 来 调用 API。 


本 书 使 用 的 工具 


以 下 是 本 书 中 用 到 的 ISON TH: 
。 JSON 编辑 器 / 建 模 工具 ， 
。 单元 测试 工具 (如 Mocha/Chai、Minitest、JUnit) ; 
。 JSON RETA, 
。 JSON Schema 生成 器 ; 
。 JSON BRIR, 
JSON 转换 (模板 ) 工具 。 


"— 合 哪些 读者 









































如 果 对 ISON 的 兴趣 仅 限于 用 JavaScript 来 发 起 Ajax 调用 ， 那 么 本 书 并 不 适合 你 。 虽 然 本 
书 也 涉及 了 Ajax 调用 ， 是 所 有 内 容 中 的 冰山 一 角 。 有 关 JavaScript 的 很 多 图 书 中 都 








包含 有 关 Ajax 调用 的 章 


本 书 不 会 包含 REST、Ruby on Rails, Java 和 JavaScript 等 内 容 的 深 入 介绍 。 本 书 会 用 到 上 


述 技术 ,但 将 关注 点 放 在 了 如 何 通 过 这 些 技术 来 使 用 JSON 上 。 


本 书 的 架构 


本 书 由 以 下 儿 部 分 内 容 组 成 : 


。 第 一 部 分 ，JSON 概述 与 平台 ; 
。 第 二 部 分 ，JSON 生态 系统 

。 第 三 部 分 ，JSON 的 企业 级 应 用 ， 
。 附录 。 


第 一 部 分 ，JSON 概 述 与 平台 


。 第 1 章 JSON 概述 





这 一 章 从 概述 ISON 数据 格式 开始 ， 描 述 使 用 ISON 过 程 中 的 最 佳 实践 ， 并 介绍 本 书 











所 使 用 的 工具 。 


。 第 2 章 在 JavaScript 中 使 用 JSON 
这 一 章 展示 了 如 何在 JavaScript, Node.js, Mocha/Chai 单元 测试 中 使 用 JSON。 


。 第 3 章 在 Rubyon Rails 中 使 用 JSON 
这 一 章 描述 了 如 何在 Ruby 对 象 和 ISON 之 间 进 行 转换 ， 以 及 如 何 与 Rails 进行 集成 。 








。 第 4 章 在 Java 中 使 用 JSON 
这 一 章 讲 述 了 如 何在 Java 和 Spring Boot 中 使 用 JSON。 


第 二 部 分 ，JSON 生 态 系统 


。 第 5 章 JSON Schema 
这 一 章 将 帮助 你 用 JSON Schema 对 JSON 文档 进行 结构 化 操作 。 同 时 ， 你 还 会 学 习 如 
何 生成 JSON Schema 并 用 其 来 设计 API。 


。 第 6 章 在 JSON 中 进行 搜索 
这 一 章 展 示 了 如 何 通 过 jq 和 JSONPath 搜索 JSON 文档 。 
。 7 章 JSON 转换 
一 章 提 供 了 工具 ， 从 而 将 设计 粳 糕 的 JSON 文档 转换 为 更 优雅 、 更 有 用 的 JSON XX 
a 。 这 一 章 还 介绍 了 如 何在 JSON 5 XML, HTML 等 其 他 格式 间 进 行 相互 转换 。 


第 三 部 分 ，JSON 的 企业 级 应 用 


。 #88 JSON 与 超 媒体 
这 一 章 介绍 了 如 何在 ISON 中 使 用 多 种 知名 的 超 媒 体格 式 ， 如 HAL 和 jsonapi。 


。 第 9 章 JSON 与 MongoDB 
这 一 章 展示 了 如 何 使 用 MongoDB 来 存储 与 处 理 ISON 文档 。 


。 第 10 章 Ri Kafka 实现 JSON 消息 系统 
这 一 章 描述 了 如 何 使 用 Apache Kafka 在 服务 间 交 换 JSON 消息 。 


附录 

。 附录 A 介绍 了 如 何 安装 运行 本 书 示例 所 需 的 应 用 程序 。 

。 附录 B 提供 了 更 多 有 关 ISON 社区 (如 标准 、 教 程 ) 的 信息 与 链接 ， 有 助 于 你 深入 学 习 
JSON, 


代码 示例 


本 书 中 的 所 有 代码 示例 及 网 址 链接 均 可 在 图 灵 社区 本 书页 面 免费 下 载 : http//www.ituring. 
com.cn/book/2093 , 


本 书 是 要 帮 你 完成 工作 的 。 一 般 来 说 ， 如 果 本 书 提供 了 示例 代码 ， 你 可 以 把 它 用 在 你 的 程 
序 或 文档 中 。 除 非 你 使 用 了 很 大 一 部 分 代码 ， 否 则 无 须 联 系 我 们 获得 许可 。 比 如 ， 用 本 书 
的 几 个 代码 片段 写 一 个 程序 就 无 须 获 得 许可 ， 销 售 或 分 发 O'Reilly 图 书 的 示例 光盘 则 需要 
获得 许可 ; 引用 本 书 中 的 示例 代码 回答 问题 无 须 获得 许可 ， 将 书 中 大 量 的 代码 放 到 你 的 产 
品 文档 中 则 需要 获得 许可 。 

我 们 很 希望 但 并 不 强制 要 求 你 在 引用 本 书 内 容 时 加 上 引用 说 明 。 引 用 说 明 一 般 包 括 书 
名 、 作 者 、 出 版 社 和 ISBN。 比 如 : “JSON at Work by Tom Marrs (O’Reilly). Copyright 2017 
Vertical Slice, Inc., 978-1-449-35832-7.” 































































































如 果 你 觉得 自己 对 示例 代码 的 用 法 超出 了 上 述 许可 的 范围 ， 欢 迎 你 通过 permissions@ 
oreilly.com 与 我 们 联系 。 


O'Reilly Safari 


Safari (前 身 为 Safari Books Online, http://oreilly.com/safari) 是 一 个 会 员 制 的 培训 和 参 
考 平台 ， 面 向 企业 、 政 府 、 教 育 从 业者 和 个 人 。 


E Safa a Safai 用 户 可 访问 O'Reilly Media, Harvard Business Review, 


Prentice Hall Professional, Addison-Wesley Professional, Microsoft 




















Press, Sams, Que, Peachpit Press, Focal Press, Cisco Press, John Wiley & Sons, 
Syngress, Morgan Kaufmann, IBM Redbooks, Packt, Adobe Press, FT Press, Apress, 
Manning, New Riders, McGraw-Hill, Jones & Bartlett, Course Technology 等 250 多 家 出 
版 社 的 上 千 种 图 书 、 培 训 视 频 、 学 习 路 径 、 交 互 式 教程 和 精 选 播放 列表 。 


如 需 了 解 更 多 信息 ， 请 访问 htep://oreilly.com/safari, 
联系 我 们 
请 把 对 本 书 的 评价 和 问题 发 给 出 版 社 。 


美国 : 


O'Reilly Media, Inc. 
1005 Gravenstein Highway North 
Sebastopol, CA 95472 


中 国 : 


北京 市 西城 区 西直门 南大 街 2 号 成 铬 大 厦 C 座 807 (100035) 
奥 莱 利 技术 咨询 (北京) 有 限 公 司 


O'Reilly 的 每 一 本 书 都 有 专属 网 页 ， 你 可 以 在 那儿 找到 本 书 的 相关 信息 ， 包 括 勘 误 表 、 示 例 
代码 以 及 其 他 信息 。 本 书 的 网 站 地 址 是 : http://shop.oreilly.com/product/0636920028482.do。 


对 于 本 书 的 评论 和 技术 性 问题 ， 请 发 送 电子 邮件 到 : 
bookquestions@oreilly.com 

要 了 解 更 多 O'Reilly 图 书 、 培 训 课 程 、 会 议和 新 闻 的 信息 ， 请 访问 以 下 网 站 : 
http://www.oreilly.com 


我 们 在 Facebook 的 地 址 如 下 : http://facebook.com/oreilly 





























请 关注 我 们 的 Twitter 动态 : http://twitter.com/oreillymedia 





我 们 的 YouTube 视频 地 址 如 下 : http:/www.youtube.com/oreillymedia 
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JSON 数据 格式 使 得 应 用 程序 可 以 通过 RESTful API 等 方式 在 网 络 上 进行 数据 通信 。JSON 
不 局 限于 某 项 技术 ， 本 身 非 私 有 ， 且 可 移植 。 对 于 产生 (序列 化 ) 和 读 取 ( 反 序 列 化 ) 
JSON 数据 ， 所 有 的 现代 编程 语言 (Java、JavaScript、Ruby、C#、PHP、Python、Groovy 
等 ) 和 平台 都 提供 了 良好 的 支持 。JSON 非常 简单 ， 由 对 象 、 数 组 和 名 称 - 值 对 这 三 种 
开发 人 员 所 熟悉 的 结构 体 所 组 成 。 除 了 表现 层 状态 转化 (REpresentational State Transfer, 
REST), JSON 在 以 下 环境 中 也 有 所 应 用 : 


。 Node.js (在 package.json 中 存储 项 目 元 数据 ) ; 
。 MongoDB 等 NoSQL 数据 库 ( 详 见 第 9 Et) , 
* Kafka 等 消息 平台 〈 详 见 第 10 章 )。 


1.1 JSON 是 一 项 技术 标准 


早年 间 ，REST 的 反对 者 在 批评 RESTful Web Service 时 曾 认 为 它 并 不 是 标准 ， 但 与 HTTP 
一 样 ，JSON 确实 是 一 项 技术 标准 。 无 论 是 互联 网 工程 任务 组 (Internet Engineering Task 
Force，IETF)， 还 是 Ecma 国际 〈 前 身 为 欧洲 计算 机 制造 商 协 会 ，European Computer 
Manufacturers Association，ECMA)， 都 已 经 认可 这 一 点 。JSON 由 Douglas Crockford 于 
2001 年 提出 ， 并 在 2006 年 由 IETF 通过 RFC 4627 进行 首次 标准 化 。2013 年 秋 ，Ecma H 
际 通过 ECMA 404 将 JSON 正式 标准 化 。 得 到 Ecma 国际 的 承认 后 ，Douglas Crockford 认 
为 JSON 已 经 是 一 个 正式 的 国际 数据 处 理 标准 了 。 


2014 4E 3 H, Tim Bray 发 布 了 REFC 7158 fll RFC 7159， 以 作为 Douglas Crockford 原始 标准 的 
改进 版 。 这 两 份 文档 修正 了 之 前 RFC 4627 标准 中 的 一 些 错 误 ， 并 将 其 状态 更 改 为 “废弃 ”。 



































1.2 示例 
在 继续 深入 前 ， 我 们 先 查 看 JSON 的 一 个 小 示例 。 例 1-1 展示 了 一 个 简单 的 ISON 文档 。 


f| 1-1 firstValidObject.json 
{ "thisIs": "My first JSON document" } 


一 个 合法 的 ISON 文档 一 般 属 于 以 下 两 种 情况 之 一 : 
。 由 大 括号 { 和 ] 括 起 来 的 一 个 对 象 ; 

。 由 中 括号 [ 和 ] 括 起 来 的 一 个 数组 。 

fil 1-1 展示 了 一 个 包含 单个 名 称 - 值 对 的 对 象 ， 其 中 键 "thisIs" 的 值 为 "My first JSON 
document", 

为 了 证 明 这 个 ISON 文档 是 合法 的 ， 我 们 使 用 JSONLint 来 校 验 一 下 。 将 上 述 ISON 文本 粘 
贴 到 文本 输入 框 中 ， 然 后 点 击 Validate 按钮 ， 就 会 看 到 如 图 1-1 所 示 的 页 面 
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A 
eoo JSONLint - The JSON Valic x A e 
e Q fi D jsonlint.com Vw) GC 7MeaO@rv GCE 
The JSON Validator A Tool from the Arc90 Lab. Source is on GitHub. 
Props to Douglas Crockford of JSON and JS Lint and 
Want more from JSONLint? Try JSONLint Pro Zach Carter, who provided the pure JS implementation of jsonlint. 
{ 
"this-is": "My first JSON document" 
Validate | JSON Lint is an idea from Arc90's Kindling FAQ 
Kindling 
Results 
Valid JSON 











1-1: 一 个 简单 、 合 法 的 JSON 文档 在 JSONLint 中 的 测试 结果 


ill 1-2 展示 了 一 个 简单 的 ISON 数组 。 
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例 1-2  firstValidArray.json 


[ 
"also", 
"a", 
"valid", 
"JSON", 
"doc" 

] 


f£ JSONLint 中 ， 将 ISON 数组 粘贴 到 文本 输入 框 中 ， 然 后 点 击 Validate 按钮 ， 就 会 看 到 如 
图 1-2 所 示 的 结果 。 





























A 
eoo JSONLint - The JSON Valic X \ 一 
e C fi D jsonlint.com Yd GC ZRhRovicsz 

The JSON Validator A Tool from the Arc90 Lab. Source is on GitHub 
Props to Douglas Crockford of JSON and JS Lint and 
Want more from JSONLint? Try JSONLint Pro Zach Carter, who provided the pure JS implementation of jsoniint. 
[ 
"also", 
"a^, 
"valid", 
"JSON", 
doc" 
l 
Validate | JSON Lint is an idea from Arc90's Kindling FAQ 
Kindling 
Results 
Valid JSON 











1-2: 合法 的 JSON 数组 在 JSONLint 中 的 测试 结果 
我 们 已 经 有 些 超前 了 。1.4 市 会 深入 阐述 ISON 的 语法 。 


1.3 为 什么 使 用 JSON 


Ecma 国际 和 IETF 所 做 的 标准 化 工作 帮助 ISON 获得 了 行业 认可 ， 但 使 JSON 广 为 流行 的 
却 是 其 他 一 些 因素 : 
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。 基于 JSON 的 RESTful API 的 爆发 式 增长 ; 
。 JSON 基本 数据 结构 的 简洁 性 ，; 

e JavaScript 日 渐 流行 。 
JavaScript 的 复兴 推动 了 JSON 的 流行 。 在 过 去 几 年 中 ， 我 们 见证 了 JavaScript 作为 一 
门 顶 级 编程 语言 的 峰 起 。JavaScript 生态 系统 既 包 含 了 Nodejs 这 样 的 平台 ， 也 包含 了 
AngularJS, React, Backbone 和 Ember 这 样 的 模型 /视图 /控制 器 (Mode/View/Controller, 
MVC) 框架 。 有 关 JavaScript 对 象 和 模式 最 佳 实践 的 图 书 和 网 站 也 层出不穷 。 按 照 
Douglas Crockford 的 说 法 ，JSON 是 JavaScript 对 象 字面 量 表示 法 的 一 个 子 集 ， 因 此 可 以 无 
缝 地 与 JavaScript 开发 融 为 一 体 。 

数 以 生计 的 RESTful API 使 用 了 JSON。 以 下 是 基于 ISON 的 一 些 流行 的 RESTful API: 


* LinkedIn 
* Twitter 




















e Facebook 

e Salesforce 

e GitHub 

e DropBox 

* Tumblr 

* Amazon Web Services (AWS) 


如 果 想 要 查看 这 几 千 个 基于 ISON 的 RESTful API， 可 以 访问 ProgrammableWeb, #2836 
fis] REST 和 JSON， 然 后 花 上 好 几 周 来 查阅 结果 。 

JSON 非常 简洁 ， 并 且 正 在 逐步 替代 XML 成 为 互联 网 上 主要 的 数据 交换 格式 。 它 易于 阅 
读 ， 相 关 结 构 也 很 容易 与 软件 开发 人 员 所 熟悉 的 概念 对 应 起 来 ， 如 数组 、 对 象 和 名 称 - 值 
对 。 我 们 不 用 再 挠 头 苦 思 某 个 东西 应 当 是 元 素 还 是 属性 ， 也 不 用 再 就 这 一 点 与 人 争论 不 
fk, 5 XML 相 比 ， 对 象 及 其 数据 成 员 这 一 组 合 更 适合 面向 对 象 的 设计 和 开发 。 由 于 节 
省 了 每 个 数据 元 素 的 开始 标签 与 结束 标签 ，JSON 格式 的 额外 开销 更 少 、 更 为 紧凑 ， 所 以 
JSON 格式 的 文档 一 般 比 内 容 相 同 的 XML 文档 小 。 从 企业 级 应 用 的 角度 来 看 ， 与 XML 相 
tk, JSON 文档 在 网 络 上 的 传输 与 处 理 更 快 ， 因 此 效率 更 高 。 


虽然 Douglas Crockford 在 提出 JSON 时 将 其 设计 为 一 种 数据 交换 格式 (通常 用 于 REST), 
但 如 今 JSON 在 配置 文件 领域 也 占有 一 席 之 地 ， 如 Node.js 和 Sublime Text 等 广泛 使 用 的 产 
ti. Node.js 使 用 package.json 文件 来 定义 其 标准 的 npm 包 结 构 ， 第 2 章 将 对 此 进行 详细 曾 
yh, Sublime Text 则 是 Web 开发 社区 中 流行 的 一 款 IDE, CEH ISON 来 配置 外 观 及 包 管 
理 器 。 


1.4 ” JSON 的 核心 概念 


JSON 的 核心 数据 格式 包括 ISON 数据 类 型 和 ISON 值 类 型 。 对 于 ISON 的 版 本 、 注 释 以 及 
文件 /MIME 类 型 ， 本 节 也 会 有 所 提 及 。 




































































1.4.1 JSON 数 据 类 型 
JSON 包括 以 下 3 种 核心 数据 类 型 。 
名 称 一 值 对 
由 一 个 名 称 (数据 属性 ) 和 一 个 值 组 成 。 
对 象 

名 称 - 值 对 的 无 序 集合 。 
数组 

值 的 有 序 集 合 。 
描述 了 基本 定义 后 ， 我 们 来 深入 了 解 一 下 每 种 数据 类 型 。 
1. 名 称 - 值 对 
例 1-3 展示 了 名 称 - 值 对 的 一 个 示例 。 


例 1-3 nameValue.json 
{ 


"conference": "OSCON", 
"speechTitle": "JSON at Work", 
"track": "Web APIs" 

















AR — (ETAL FEE. 

。 每 一 个 键 名 (如 "conference" ) 
- 位 于 冒号 (:) 左边 ; 
- 是 一 个 字符 串 ， 而 且 必 须 由 双 引 号 括 起 来 。 

。 值 (如 "0scoN") 位 于 冒号 的 右边 。 在 上 述 示例 中 ， 值 的 类 型 为 字符 串 ， 但 还 存在 多 种 
其 他 值 类 型 。 

1.4.2 节 将 对 字符 串 和 其 他 合法 的 值 类 型 进行 介绍 。 

2. 对 象 

对 象 由 名 称 - 值 对 组 成 。 例 1-4 展示 了 一 个 表示 地 址 的 对 象 。 


f| 1-4 simpleJsonObject.json 









































{ 
"address" : { 
"Linei" : "555 Any Street", 
"city" : "Denver", 
"stateOrProvince" : "CO", 
"zipOrPostalCode" : "80202", 
"country" : "USA" 
} 
} 





例 1-5 RAS S/F A AN BAT R 
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例 1-5 jsonObjectNestedArray.json 


{ 
"speaker" : { 
"firstName": "Larson", 
"LastName": "Richard", 
"topics": [ "JSON", "REST", "SOA" ] 
} 
} 


例 1-6 Js T NARRER RAT R 
例 1-6  jsonObjectNestedObject.json 


{ 
"speaker" : { 
"firstName": "Larson", 
"lastName": "Richard", 
"topics": [ "JSON", "REST", "SOA" ], 
"address" : { 
"line1" : "555 Any Street", 
"city" : "Denver", 
"stateOrProvince" : "CO", 
"zipOrPostalCode" : "80202", 
"country" : "USA" 
} 
} 
} 
对 象 具有 以 下 特征 : 


。 由 左 大 括号 { 和 右 大 括号 } 括 起 来 ; 
由 一 些 无 序 的 名 称 - 值 对 组 成 ， 以 过 号 分 隔 ; 
。 可 以 是 空 对 象 { 3s 
可 以 内 上 租 在 其 他 对 象 或 者 数组 中 。 
3. 数组 
例 1-7 展示 了 一 个 内 和 肯 其 他 对 象 和 数组 的 数组 ， 该 数组 描述 了 包含 标题 、 长 度 和 摘要 信息 
9 会 议 报告 。 
例 1-7 jsonArray.json 
{ 


"presentations": [ 


{ 








"title": "JSON at Work: Overview and Ecosystem", 
"length": "90 minutes", 
"abstract": [ "JSON is more than just a simple replacement for XML when", 
"you make an AJAX call." 
]， 
"track": "Web APIs" 
}, 
{ 
"title": "RESTful Security at Work", 
"Length": "90 minutes", 
"abstract": [ "You've been working with RESTful Web Services for a few years", 





"now, and you'd like to know if your services are secure." 


l. 
"track": "Web APIs" 


] 
} 


数组 具有 以 下 特征 : 

。 由 左 中 括号 [ 和 右 中 括号 ] 括 起 来 ， 

。 由 一 些 有 序 的 值 组 成 ， 以 逗号 分 隔 〈 详 见 下 节 ) ; 
。 可 以 是 空 数组 []; 

。 可 以 内 磐 在 其 他 数组 或 者 对 象 中 ， 

。 具有 以 08 或 1 开头 的 索引 。 


1.4.2 JSON 值 类 型 
ISON 值 类 型 用 于 表示 出 现在 名 称 - 值 对 冒号 G) 右 侧 的 数据 类 型 。 这 些 类 型 包括 : 


。 对 象 
。 数组 
。 字符 串 
。 数值 
。 布尔 值 
e null 


前 面 已 经 介绍 过 对 象 和 数组 ， 接 下 来 我 们 看 一 下 其 他 的 值 类 型 : 字符 串 、 数 值 、 布 尔 值 和 
null, 

1. 字符 串 

例 1-8 展示 了 一 些 合 法 的 ISON 字符 串 。 


例 1-8 jsonString.json 


[ 
"fred", 
"fred\t", 
"Nb" y 












































Lu 


"ie", 
"\u004A" 


字符 串 具 有 以 下 特征 。 


。 由 包含 在 双 引 号 ("") 间 的 零 个 或 多 个 Unicode 字符 组 成 。 除 此 之 外 ， 还 包括 以 下 列举 
的 一 些 字符 。 
。 由 单 引号 (C) 引起 来 的 字符 串 为 非法 字符 8 


JSON 字符 串 还 可 以 包含 由 反 斜 杠 转 义 的 字符 ， 如 下 所 示 : 

















pum 











o 
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RAL 





IERHT 


Mt 
Tab 制 表 符 


\u 
后 跟 4 个 十 六 进 制 数字 (表示 一 个 Unicode 字符 ) 


2. 数值 
例 1-9 展示 了 一 些 合 法 的 JSON 数值 。 


例 1-9 jsonNumbers.json 

{ 
"age": 29, 
"cost": 299.99, 
"temperature": -10.5, 
"unitCost": 0.2, 
"speedOfLight": 1.23e11, 
"speedOfLight2": 1.23e+11, 
"avogadro": 6.023E23, 
"avogadro2": 6.023E+23, 
"oneHundredth": 10e-3, 
"oneTenth": 10E-2 

} 


数值 遵循 JavaScript 的 双 精 度 序 点 数 格式 ， 并 且 具 有 以 下 特征 。 

。 数值 永远 是 十 进 制 数 (只 能 出 现 数 字 0~9) ， 不 能 以 0 开头 。 

。 数值 可 以 存在 由 小 数 点 (.) 开头 的 小 数 部 分 。 

。 数值 可 以 是 以 10 为 底 的 指数 ， 该 指数 由 e 或 E 来 表示 ， 其 后 跟 正 号 表示 正 指数 寡 ， 跟 
负 有 号 则 表示 负 指 数 寡 。 

。 数值 不 支持 八进制 数 和 十 六 进 制 数 。 
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e 与 JavaScript 不 同 ， 数 值 不 能 是 NaN (Not a Number， 用 于 表示 非法 数值 )， 也 不 能 是 
Infinity, 


3. 布尔 值 


例 1-10 展示 了 JSON 中 的 布尔 值 。 














例 1-10  jsonBoolean.json 


{ 


} 


"isRegistered": true, 
"emailValidated": false 


布尔 值 具 有 以 下 特征 。 

。 只 存在 两 种 值 : true 或 false, 
。 冒号 〈:) 右边 的 true 或 者 false 不 能 由 引号 括 起 来 。 
4.null 
从 技术 上 来 说 ，null 并 不 是 一 种 值 类 型 ， 而 是 ISON 中 的 一 个 特殊 值 。 例 1-11 展示 了 





line2 





这 一 属性 的 值 为 null。 


例 1-11 jsonNull.json 


{ 


} 


"address": { 
"Linei": "555 Any Street", 
"Line2": null, 

"city": "Denver", 
"stateOrProvince": "CO", 
"zipOrPostalCode": "80202", 
"country": "USA" 


} 


null 具有 以 下 特征 。 


不 能 由 引号 括 起 来 。 
表示 某 个 键 或 属性 没有 值 。 
用 作 占 位 符 。 





1.4.3 ”JSON 的 版 本 


根据 Douglas Crockford 的 说 法 ，JSON 的 核心 标准 不 会 再 有 新 的 版 本 。 这 倒 不 是 说 ISON 
是 完美 的 ， 毕 竟 没 有 什么 是 完美 的 。JSON 标准 唯一 化 的 目的 是 避免 为 支持 早期 版 本 而 在 
向 后 兼容 的 过 程 中 遭遇 陷阱 。Crockford iA, 247] 
替代 ISON. 


{HIER 

















nde POR AU SE TTA, “ACHR AS” 





F 发 社区 有 新 的 需要 时 ， 新 的 数据 格式 将 








的 理念 


又 适用 于 JSON 的 核心 数据 格式 。 比 如 ， 


第 5 章 中 提 到 的 相关 标准 在 编写 本 书 时 的 版 本 号 为 0.5。 值 得 一 提 的 是 ， 与 JSON 有 关 的 这 
些 标准 是 由 JSON 社区 中 的 其 他 人 员 所 提 昌 


























HAY. 
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1.4.4 JSON 中 的 注释 
一 言 以 项 之 ，JSON 中 没有 注释 。 


根据 Crockford 在 Yahoo! JSON group 和 Google+ 上 的 说 法 ，JSON 最 开始 是 允许 出 现 注释 

的 ,但 之 后 不 久 就 因为 以 下 原因 移 除了 注释 。 

e Crockford 认为 注释 没有 什么 用 处 。 

。 JSON 解析 器 在 支持 注释 方面 存在 困难 。 

。 出 现 了 滥用 注释 的 情况 。Crockford 发 现 有 些 注释 被 用 于 解析 指令 ， 而 这 会 彻底 挫 毁 
JSON 的 互 操作 性 。 

。 移 除 注释 有 利于 ISON 实现 跨 平台 性 ， 简 化 这 方面 的 支持 工作 。 


1.4.5 ” JSON 文件 及 MIME 类 型 


根据 JSON 的 核心 标准 文档 ，.json 是 在 文件 系统 中 存储 JSON 数据 的 标准 文件 类 型 。 在 
互联 网 号 码 分 配 局 (Internet Assigned Numbers Authority, IANA) F, JSON 的 媒体 类 型 
(或 者 说 MIME) 为 appLication/json， 这 可 以 在 IANA 的 媒体 类 型 网 站 上 找到 。 通 过 在 
HTTP 头 部 中 声明 ISON 媒体 类 型 ，RESTful Web Service 的 开发 者 和 使 用 者 一 般 使 用 这 种 
名 为 内 容 协商 的 机 制 来 表明 自己 正在 使 用 JSON 进行 数据 交换 。 


1.4.6 ” ”JSON 编码 规范 


JSON 的 意义 在 于 互 操作 性 ， 因 此 以 使 用 者 期 望 的 方式 提供 数据 是 非常 重要 的 。 为 了 总 结 
最 佳 实践 ， 提 升 可 维护 性 ，Google 发 布 了 JSON 编码 规范 


这 份 规范 非常 详细 ， 其 中 对 于 API 设计 者 和 开发 者 来 说 最 重要 的 是 以 下 三 点 




























































































。 JETER; 

。 日 期 属性 的 值 ， 

。 枚 举 值 。 

1. 属性 名 

按照 Google 的 说 法 ， 属 性 名 位 于 名 称 - 值 对 中 冒号 的 左 侧 (属性 值 则 位 于 右 侧 )。JSON 
属性 名 的 风格 主要 有 两 种 : 


。 小 驼峰 式 命名 法 (lowerCamelCase) ; 

。 以 下 划 线 分 隔 的 短语 (snake case), 

当 使 用 小 驼峰 式 命 名 法 时 ， 属 性 名 是 由 单个 或 多 个 词 拼 接 而 成 的 一 个 “单词 ”， 其 中 除 第 
一 个 词 外 ， 其 余 每 个 词 均 以 大 写字 母 开 头 。Java 社区 和 JavaScript 社区 在 编码 规范 上 均 使 
用 了 小 驼峰 式 命 名 法 。 当 使 用 以 下 划 线 分 隔 的 短语 时 ， 所 有 的 字母 均 小 写 ， 词 与 词 之 间 以 
下 划 线 (C) 分 隔 。Ruby on Rails 社区 更 偏好 这 种 命名 法 。 


与 多 数 RESTful API 一 样 ，Google 在 属性 名 上 使 用 了 小 驼峰 式 命名 法 ， 如 例 1-12 所 示 。 









































例 1-12 jsonPropertyName.json 
{ 


"firstName": "John Smith" 


} 


2. 日 期 属性 的 值 

你 可 能 认为 日 期 的 格式 并 不 那么 重要 ， 但 实际 上 其 重要 性 毋庸 置疑 。 想 象 在 来 自 不 同 国家 
或 大 陆 的 数据 提供 者 与 使 用 者 之 间 交 换 日 期 信息 。 即 使 在 同一 家 公司 ， 两 个 开发 小 组 也 可 
能 使 用 不 同 的 日 期 格式 。 思 考 在 语义 上 如 何 解释 时 间 戳 ， 从 而 在 所 有 时 区 采用 一 致 的 日 期 / 
时 间 处 理 机 制 并 保持 互 操作 性 ， 是 非常 重要 的 。Google 的 ISON 编码 规范 偏好 让 日 期 遵循 
RFC 3339 的 格式 ， 如 例 1-13 所 示 。 


例 1-13 jsonDateFormat.json 


{ 
"dateRegistered": "2014-03-01T23:46:11-05:00" 


} 


以 上 日 期 使 用 了 协调 世界 时 «(Coordinated Universal Time, UTC) fZ —5 小 时 的 时 区 (以 
格林 尼 治 标准 时 间 UTC/GMT 作为 基准 计算 )， 即 美国 东部 时 间 。 值 得 注意 的 是 ，RFC 
3339 是 ISO 8601 的 一 个 概括 。 两 者 的 主要 区 别 在 于 ，ISO 8601 允许 将 用 于 分 隔日 斯 和 时 
间 的 T 字符 赫 换 为 空格 ，RFC 3339 则 不 允许 这 么 做 。 


3. 经 纬度 值 

Google Maps 等 地 理 信 息 API 以 及 与 地 理 信息 系统 相关 的 其 他 API 会 用 到 经 纬度 数据 。 为 
了 保持 一 致 性 ，Google 的 ISON 编码 规范 建议 使 用 经 纬度 数据 时 遵循 ISO 6709 标准 。 根 
据 Google Maps 所 提供 的 信息 ， 美 国 纽约 帝国 大 厦 的 经 纬度 为 北纬 40.748747 度 ， 西 经 
73.985547 度 ， 这 在 JSON 中 的 表示 如 例 1-14 所 示 。 


f| 1-14  jsonLatLon.json 


{ 
"empireStateBuilding": "40.748747-73.985547" 































































































上 例 中 的 经 纬度 以 x DD.DDDD + DDD.DDDD 的 格式 表示 ， 同 时 遵循 以 下 约定 。 


。 纬度 在 前 ， 经 度 在 后 。 

。 北半球 的 纬度 为 正 数 。 

。 本 初子 午 线 以 东 的 经 度 为 正 数 。 

。 经 纬度 值 以 字符 串 表 示 。 因 为 可 能 存在 负 号 ， 所 以 无 法 用 数值 表示 作为 一 个 整体 的 经 
纬度 。 

4. 缩 进 

虽然 Google 的 JSON 编码 规范 并 未 提 及 缩 进 这 一 话题 ， 不 过 大 致 存在 以 下 规则 。 

。 JSON 是 一 种 序列 化 格式 ， 而 不 是 呈现 格式 。 因 此 ， 缩 进 对 于 API 的 提供 者 和 使 用 者 来 
说 意义 不 大 。 

。 在 优化 JSON 文档 的 显示 时 ,很 多 JSON 格式 化 工具 会 让 使 用 者 选择 具体 的 缩 进 方案 (两 
格 缩 进 、 三 格 缩 进 、 四 格 缩 进 等 ) 。 
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。 JSON 起 源 于 JavaScript， 并 已 成 为 ECMA 262 标准 的 一 部 分 。 但 遗憾 的 是 ，JavaScript 
社区 在 缩 进 问 题 上 并 未 达成 共识 。 很 多 人 以 及 不 少 编码 规范 中 都 偏好 使 用 两 格 缩 进 ， 因 
此 本 书 也 遵循 了 这 一 惯例 。 当 然 ， 只 要 保持 一 致 ， 你 也 可 以 选择 其 他 缩 进 风 格 。 


1.5 本 书 示例 : MyConference 
本 书 的 所 有 示例 都 与 会 议 数据 有 关 ， 具 体 包 括 以 下 两 方面 ; 


。 会 议 的 演讲 者 ， 
。 会 议 的 主题 演讲 。 


1.5.1 本 书 技术 栈 


我 们 将 先 创 建 一 段 简单 的 JSON 数据 ， 用 于 表示 会 议 演讲 者 ， 然 后 将 其 发 布 为 一 个 模拟 的 
RESTful API。 具 体 的 操作 步骤 如 下 所 示 。 


(1) 用 JSON Editor Online 对 JSON 数据 进行 建 模 。 
(2) FH JSON Generator 生成 示例 数据 。 
(3) 创建 并 部 署 模拟 API， 为 之 后 的 测试 工作 做 准备 。 


1.5.2 ”本 书架 构 风 格 : noBackend 


本 书 的 架构 风格 是 基于 noBackend 的 理念 形成 的 。 如 果 采 用 noBackend 的 理念 ， 开 发 人 员 
就 无 须 在 应 用 程序 开发 的 早期 阶段 ， 烦 心 于 服务 器 和 数据 库 等 具体 细节 。 


本 书 前 7 章 的 示例 采用 了 noBackend 的 架构 ， 目 的 是 从 业务 角度 (服务 与 数据 优先 ) 关注 

应 用 程序 的 开发 ， 从 而 使 得 应 用 程序 不 仅 能 支持 移动 端 、 平 板 和 网 页 等 UI 客户 端 ， 同 时 

也 能 支持 API 调用 和 非 Web 客户 端 。JSON 数据 会 由 json-server 这 样 的 小 工具 来 部 署 ， 

从 而 模拟 实现 RESTful API。 

采用 这 一 接口 先行 的 策略 来 设计 和 构建 API 能 带 来 诸多 好 处 。 

。 因为 与 后 端 解 耦 ， 所 以 前 端 开发 会 变 得 更 加 敏捷 、 快 速 和 友 代 化 。 

。 API 本 身 能 够 更 加 快速 地 获得 反馈 。 将 API 的 URI 和 数据 快速 推 向 市 场 有 助 于 更 快 得 
到 审阅 。 

。 有 助 于 得 到 一 个 更 加 清晰 、 整 洁 的 API 接口 。 

。 关注 点 分 离 。 将 API 暴露 的 资源 (如 以 JSON 数据 表示 的 会 议 演讲 者 ) 与 其 最 终 内 部 实 
现 (如 应 用 程序 服务 器 、 业 务 逻辑 、 数 据 存 储 等 ) 分 离 。 这 可 以 使 得 后 续 修 改 具 体 实现 
变 得 更 加 简单 。 如 果 过 早 创建 和 部 署 由 Node.js、Rails、Java (或 者 其 他 框架 ) 所 开发 
的 真实 API"， 则 意味 着 在 非常 早 的 阶段 就 确定 了 具体 的 设计 决策 ， 这 会 导致 最 后 和 API 
的 使 用 者 进行 磨合 时 ， 修 改 的 难度 会 增加 。 


使 用 模拟 API 能 够 带 来 以 下 便利 。 


。 不 必 在 项 目 初期 进行 服务 器 和 数据 库 方面 的 工作 。 
。 允许 API 的 提供 者 ( 写 API 的 开发 人 员 ) 专注 于 API 设 计 ， 聚 焦 于 如 何 用 最 好 的 方式 
向 使 用 者 呈现 数据 ， 同 时 执行 最 初 阶段 的 测试 。 
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。 使 得 API 的 使 用 者 (UI 开发 人 员 ) 能 够 在 早期 阶段 和 API 对 接 ， 并 向 API 的 开发 团队 
提供 反馈 。 

在 编写 代码 并 部 署 到 服务 器 之 前 ， 通 过 使 用 本 书 中 所 提 到 的 轻 量 级 工具 ， 你 可 以 完成 很 

多 工作 。 当 然 ， 最 终 还 是 需要 实现 API 的， 第 2-4 章 在 介绍 JavaScript, Ruby on Rails 和 

Java 时 会 展示 具体 的 实现 方法 。 


1.5.3 用 JSON Editor Online 对 JSON 数 据 进 行 建 模 

创建 大 小 和 复杂 度 都 比较 真实 的 合法 ISON 文档 繁琐 且 易 错 。 在 这 一 点 上 ，JSON Editor 

Online 是 一 个 很 不 错 的 Web 工具 ， 提 供 了 以 下 便利 。 

。 支持 用 对 象 、 数 组 和 名 称 - 值 对 的 方式 对 JSON 文档 进行 建 模 。 

。 使 得 快速 遍历 生成 JSON 文档 的 操作 变 得 更 加 简单 。 

JSONmate 是 另 一 个 比较 不 错 的 编辑 器 ， 但 本 书 不 会 详细 介绍 。 

1. JSON Editor Online 的 功能 

除了 JSON 建 模 和 文档 生成 ，JSON Editor Online 还 提供 以 下 功能 。 

JSON 校 验 
当 在 页 面 左 侧 的 ISON 文本 框 中 输入 ISON 数据 时 ， 这 些 数据 就 会 被 校 验 。 如 果 遗 漏 了 
MAMA MSS (如 "firstName":"Ester,)， 则 JSON 文本 中 的 下 一 行 会 出 现 X 标 
记 。 当 鼠标 悬浮 在 该 标记 上 时 ， 就 会 显示 校 验 错误 的 具体 原因 。 
































优化 显示 效果 
点 击 ISON 文本 框 区 域 左 上 角 的 Indent 按钮 可 以 优化 JSON 文档 的 显示 效果 。 
模型 与 文本 之 间 的 双向 工程 








在 页 面 右 侧 的 ISON 模型 中 使 用 添加 按钮 (+) ， 可 以 往 模 型 中 添加 一 些 对 象 和 名 称 - 值 
对 ， 然 后 点 击 页 面 中 间 偏 上 方 的 左 箭头 按钮 即 可 生成 JSON 文本 。 可 以 在 页 面 左 侧 的 
JSON 文本 框 中 看 到 相应 的 变化 。 
同样 ， 在 ISON 文本 框 中 对 数据 进行 修改 ， 然 后 点 击 右 箭头 按钮 即 可 在 页 面 右 侧 的 ISON 
模型 中 看 到 相应 的 改变 。 
将 JSON X B HR E ELS XE 
通过 选择 Save 菜单 中 的 Save to Disk 选项 ， 可 以 将 JSON 文档 保存 到 本 地 机 器 中 。 
导入 JSON 文档 
通过 选择 Open 菜单 中 的 Open from Disk 选项 ， 可 以 导入 计算 机 中 的 ISON 文档 。 
需要 注意 的 是 ，JSON Editor Online 是 一 个 公用 工具 ， 粘 贴 到 该 应 用 程序 中 的 所 有 数据 对 于 
其 他 人 来 说 都 是 可 见 的 。 因 此 ， 请 勿 使 用 该 工具 处 理 个 人 、 财 产 等 隐私 信息 。 
2. JSON Editor Online 中 的 会 议 演 讲 者 数据 
完成 对 演讲 者 数据 的 建 模 后 ， 点 击 左 箭头 按钮 ， 即 可 生成 优化 缩 进 显示 后 的 JSON 文档 。 
图 1-3 展示 了 JSON Editor Online 以 及 初始 演讲 者 数据 模型 。 
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JSON Editor Online New Open v Save v Settings v Help 


ER 
amt v object (1) 
2- "speakers": [ » 
3- { v speakers [3] 
4 "about": "Incididunt mollit cupidatat magna excepteur do » 
tempor ex non eiusmod magna exercitation proident nisi non. id v 9 (8) 


Sunt Md /consequit eu non esse excepteur. Veniam quus Loren about : Incididunt mollit cupidatat magna excepteur do 
ea labore ullamco veniam nisi do sunt. Nisi irure sit qui eapo ex non eiusmod magna exercitation 
irure mollit ad aliquip non culpa sint reprehenderit ullamco proident nisi non. Sunt ad consequat eu non 

M esse excepteur. Veniam quis Lorem ea labore 


5 "company": "Ecratic", ullamco veniam nisi do sunt. Nisi irure sit 
6 "email": “larsonrichard@ecratic.com", qui irure mollit ad aliquip non culpa sint 
E "firstName": "Larson" reprehenderit ullamco. \r\n 
8 "id": 6, company : Ecratic 
9 "lastName": " Richard", 
10 "picture": "http://placehold.it/32x32", email : larsonrichard@ecratic.com 
11- "tags": [ : 
12 "JavaScript", "AngularJs", "Yeoman" firstiame.: Larson 
13 ] id :9 
14 b 
15- { lastName : Richard 
16 "about": "Labore tempor irure adipisicing consectetur velit. . 5 
Ipsum Lorem non mollit aliquip. Fugiat est irure quis picture : http: //placehold.it/32x32 


laboris minim anim esse fugiat et culpa exercitation. Dolor 
cillum excepteur officia Lorem ullamco magna et cupidatat > tags [3] 
dolor incididunt occaecat adipisicing consectetur in. » 1 (8) 
Ullamco ullamco commodo nulla eiusmod. Lorem Lorem non sunt s 
laboris ut et elit mollit deserunt nostrud est et id » 2 {8} 
adipisicing. 

17 "company": "Acusage", 

18 email": "esterclementsgacusage.con* 

: "Ester", 





21 "lastName": "Clements", 

22 "picture": "http://placehold.it/32x32", 

23+ "tags": [ 

24 "REST", "Ruby on Rails", "APIs" 

25 1 

26 » 

27 -~ 

28 "about": "Proident ex Lorem et Lorem ad. Do voluptate officia 





图 1-3: JSON Editor Online 中 的 演讲 者 数据 模型 


尽管 这 个 模型 比较 粗糙 ， 却 是 一 个 不 错 的 开始 。 可 以 使 用 这 一 模型 对 ISON 数据 进行 可 视 
化 、 在 早期 阶段 收集 反馈 ， 这 一 策略 可 以 帮助 你 在 整个 开发 周期 
中 改善 JSON 数据 结构 ， 而 无 须 在 基础 架构 和 具体 实现 上 耗费 大 量 时 间 和 精力 。 


1.5.4 用 JSON Generator 生 成 示例 数据 


使 用 JSON Editor Online 是 一 个 不 错 的 开端 ， 但 我 们 真正 需要 的 其 实 是 快速 生成 大 量 的 测 
试 数据 。 由 于 隐私 数据 的 敏感 性 ， 以 及 任何 正式 测试 对 数据 量 的 庞大 需求 ， 生 成 测试 数据 
会 显得 比较 琼 手 。 对 于 这 一 问题 ， 即 使 使 用 ISON Editor Online， 也 会 在 创建 所 需 的 测试 数 
据 上 耗费 大 量 精力 。 因 此 ， 我 们 需要 别 的 工具 来 帮助 生成 第 一 版 API 所 需 的 数据 。 这 个 优 
秀 工 具 就 是 用 于 生成 测试 数据 文件 speakers.json 的 JSON Generator。 用 于 生成 speakers.json 
文件 的 模板 可 以 在 GitHub 上 找到 。 第 5 章 将 详细 介绍 JSON Generator 的 用 法 。 


1.5.5 创建 并 部 署 模拟 API 

我 们 会 将 刚 创建 的 会 议 演讲 者 测试 数据 部 署 为 RESTful API， 从 而 创建 出 一 个 模拟 的 API 
服务 。 < speakers.json 文件 暴露 为 Web API， 从 而 快速 制作 原型 ， 我 们 会 使 用 json- 
server 3X — Node.js 模块 。 关 于 json-server， 可 以 在 其 GitHub 页 面 上 找到 更 多 相关 信息 。 
在 继续 深入 之 前 ， 需 要 搭建 好 开发 环境 ， 请 先 参考 附录 A 来 执行 以 下 步骤 。 


(1) 安装 Node.js, json-server 是 一 个 Node.js 模块 ， 因 此 首先 得 安装 Node.js。 可 以 参考 
A.2 节 中 的 相关 内 容 。 
























































(2) 安装 json-server, ALB A.2.5 n, 

(3) 安装 JSONView 和 Postman， 可 以 参考 A.1 节 。JSONView 可 以 在 Chrome 和 Firefox 中 
优化 JSON 的 显示 。Postman 可 以 在 大 多 数 主流 操作 系统 中 以 独立 的 GUI 应 用 程序 的 形 
式 来 运行 。 

打开 终端 ， 在 命令 行 中 用 5000 端口 来 启动 json-server， 如 下 所 示 : 


cd chapter-1 




















json-server -p 5000 ./speakers.json 

















可 以 看 到 以 下 执行 结果 : 


json-at-work => json-server -p 5000 ./speakers.json 





NfA_AH hi! 


Resources 
http: //localhost:5000/speakers 


Home 
http://localhost :5000 








在 浏览 器 中 访问 http:Wlocalhost:5000/speakers， 即 可 看 到 由 模拟 API 所 提供 的 (经 过 
JSONView 优化 显示 的 ) 所 有 演讲 者 数据 ， 如 图 1-4 所 示 。 




















e TT localhost:5000/speakers > Tom 
e i localhost:5000/speakers 2 t R, d$ e] = 
Cfi | pea Ca iG L] el Y [os] e (2h 
[ 
-í 
about: "Incididunt mollit cupidatat magna excepteur do tempor ex non eiusmod magna exercitation proident nisi non. Sunt ad consequat eu non esse 
3 . Veniam quis Lorem ea labore ullamco veniam nisi do sunt. Nisi irure sit qui irure mollit ad aliquip non culpa sint reprehenderit 
Ecratic", 
arsonrichardéecrat. com’ 
firstName: "Larson", 
id: 0, 
lastName: Richard", 
picture: "http://placehold.it/32x32", 
- tags: [ 
be 
-4 
company: "Aci 
email: "esti 
firstName: 
id: 1, 
lastName: "Clements", 
picture: "http://placehold.it/32x32", 
- tags: [ 
REST", 
Ruby on Rails 
"APIS" 
1 
be 
-4 
nostrud do ut. Aute ad dolor tempor dolor aute nisi 
ul nt incididunt dolore et magna aliquip ut ex. Cupidatat 
st. Culpa veniam ut excepteur aliqua exercitation. 
[ol.about 











图 1-4: 在 浏览 器 中 用 JSONView 显示 由 json-server 提供 的 演讲 者 数据 
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还 可 以 通过 往 URI 中 添加 id 来 获取 单个 演讲 者 的 信息 ， 如 http://localhost:5000/speakers/0, 


效果 还 不 错 ， 但 使 用 广 览 器 进行 测试 时 只 能 发 送 HTTP GET 请 求 ， 因 此 存在 一 定 的 局 限 性 。 
而 Postman 既 可 以 发 送 HTTP 的 GET, POST, PUT 和 DELETE 请 求 ， 还 可 以 设置 HTTP 头 部 ， 


因此 具备 对 RESTful API 进行 完整 测试 的 能 





可 以 使 用 Postman 删除 API 中 第 一 个 演讲 者 的 数据 ， 有 具体 步骤 如 下 所 示 。 


(1) 输 入 URL: http;//localhost:5000/speakers/O , 
(2) 选择 DELETE 作为 HTTP 方法 。 
(3) 点 击 Send 按钮 。 





Postman 中 的 DELETE 请 求 正 常 运行 ， 获 取 到 的 HTTP 响应 码 为 200 (OK). ， 如 图 1-5 所 示 。 





DELETE http;//localhost:5000/speakers/0 


Authorization 


Type No Auth 


Body (13) 


Pretty JSON 


1 \f 





Params Send Save 








1-5; Postman 删除 第 一 个 演讲 者 的 请 求 结果 


在 浏览 器 中 再 次 访问 http://localhost:5000/speakers/0， 以 确认 删除 了 第 一 个 演讲 者 的 数据 。 


响应 的 数据 应 当 是 空 的 ， 如 图 1-6 所 示 。 





€ > Œ | © localhost:5000/speakers/O 


C) 











1-6: 验证 删除 第 一 个 演讲 者 的 结果 


如 果 需 要 关闭 json-server, HEMA fin md: Ctrl-C, 


有 了 模拟 API 后 ， 就 可 以 用 任意 一 种 HTTP 客户 端 (Javas 
进行 调用 ， 以 外 部 应 用 程序 的 形式 使 用 测试 数据 。 虽 然 本 








cript、Ruby 或 者 Java 等 ) 对 其 
后 续 章 节 中 的 示例 大 多 使 用 了 





HTTP GET 方法 ， 但 实际 上 json-server 支持 所 有 核心 的 HTTP 请 求 类 型 (GET, POST, PUT, 
DELETE) 。 值 得 一 提 的 是 ， 本 书 中 并 未 详细 介绍 的 Mountebank 也 是 一 个 不 错 的 服务 器 工具 ， 
在 对 API 和 协议 的 模拟 方面 可 以 提供 更 健壮 的 功能 。 


使 用 模拟 API 的 关键 点 在 于 : 在 不 编写 任何 代码 的 情况 下 ，API 的 提供 者 可 以 利用 JSON 
工具 来 制作 可 测试 的 RESTful API 原型 。 这 一 技术 使 得 API 的 使 用 者 无 须 等 待 API 10096 
完成 即 可 开始 测试 工作 ， 因 此 非常 有 用 。 在 API 的 使 用 者 测试 模拟 API 的 同时 ，API 的 开 
发 团队 可 以 对 原型 及 其 设计 进行 迭代 式 的 改进 。 


1.6 本章 回 顾 


本 章 先 介绍 了 JSON 的 基础 知识 ， 然 后 用 JSON Editor Online 对 JSON 数据 进行 了 建 模 ， 并 
将 其 部 署 为 模拟 API。 


Z3 
17 ARME 
第 2~4 章 将 介绍 JSON 在 以 下 主流 平台 上 的 使 用 : 


* JavaScript 























T 









































e Ruby on Rails 
* Java 


在 第 2 章 中 ， 你 将 利用 之 前 用 json-server 所 搭建 的 模拟 API 来 学 习 如 何在 JavaScript 中 
使 用 JSON。 
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第 2 章 


在 JavaScript 中 使 用 JSON 





我 们 在 上 一 章 中 介绍 了 JSON 数据 交换 格式 的 基础 知识 ， 本 章 则 将 开始 用 ISON 来 开发 具 
体 的 应 用 程序 。 虽 然 ISON 最 初 是 JavaScript 语言 为 对 象 和 数组 定义 的 一 个 子 集 ， 但 如 今 
它 与 JavaScript 之 间 已 经 不 存在 绑 定 关系 了 。 现 在 的 JSON 与 具体 编程 语言 无 关 ， 而 且 可 
以 跨 平台 工作 。 不 过 ， 因 为 JSON WF JavaScript， 所 以 我 们 首先 介绍 ISON 在 JavaScript 
中 的 使 用 情况 。 


本 章 内 容 如 下 所 示 : 


。 使 用 JSON.stringify() 和 JSON.parse() 进行 JavaScript 中 的 序列 化 / 反 序 列 化 操作 ， 
。 使 用 JavaScript 对 象 和 JSON; 

。 调用 RESTful API， 并 使 用 Mocha/Chai 对 调用 的 结果 进行 单元 测试 ，; 

。 搭建 基于 JSON 的 一 个 小 型 Web 应 用 程序 。 


在 本 章 的 示例 中 ， 我 们 将 会 用 到 Node.js， 并 用 Yeoman 来 快速 搭建 Web 应 用 程序 ， 然 后 
对 上 一 章 中 用 json-server 所 创建 的 RESTful API 服务 进行 调用 以 获取 数据 。 因 为 涉及 的 
概念 和 内 容 很 多 ， 所 以 我 们 会 逐个 学 习 并 应 用 。 在 开发 Web 应 用 程序 前 ， 先 来 了 解 一 下 
JavaScript 中 的 序列 化 / 反 序 列 化 和 对 象 方面 的 基础 知识 。 



































2.1 安装 Node.js 
正式 开始 前 ， 可 以 参考 A2 节 中 的 操作 说 明 来 搭建 开发 环境 。 
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2.2 ”用 JSoN.stringify() 和 JSON.parse() 进 行 序列 
化 / 反 序 列 化 操作 


为 了 以 跨 平 台 的 方式 向 其 他 应 用 程序 提供 数据 ， 一 个 应 用 程序 需要 将 信息 序列 化 为 JSON。 
同时 ， 应 用 程序 还 必须 能 够 反 序列 化 JSON， 从 而 将 外 部 信息 转换 成 自身 可 理解 的 数据 结构 。 


2.2.1 用 于 stringify/parse 操 作 的 “JSON” 对 象 

用 于 stringify/parse 操作 的 “JSON” 对 象 最 初 由 Douglas Crockford 所 开发 ， 并 从 2009 
年 的 ECMAScript 5 标准 开始 成 为 JavaScript 原生 类 库 的 一 部 分 。 该 对 象 提供 以 下 方法 : 

。 JSON.stringify() 将 信息 序列 化 为 JSON; 

。 JSON.parse() 将 JSON 反 序列 化 为 JavaScript 可 以 理解 的 数据 结构 。 

另外 ， 该 对 象 还 存在 以 下 特征 : 

。 最 初 由 Douglas Crockford 所 开发 ; 

。 无 法 实例 化 ， 

。 除了 stringify() 和 parse()， 不 提供 其 他 功能 。 


2.2.2 JavaScript 中 简单 数据 类 型 的 JSON 序 列 化 操作 
我 们 先 来 看 一 下 对 JavaScript 中 的 下 列 基础 数据 类 型 的 序列 化 操作 : 

。 数值 

。 字符 串 
。 数组 
。 布尔 值 
。 字面 量 对 象 

ffi 2-1 展示 了 如 何 使 用 ISON. stringify C) 来 序列 化 简单 数据 类 型 。 
例 2-1 js/basic-data-types-stringify.js 


var age = 39; // 整 型 数 
console.log('age = ' + JSON.stringify(age) + '\n'); 

































































var fullName = 'Larson Richard'; // 字符 串 
console. log('fullName = ' + JSON.stringify(fullName) + '\n'); 


var tags = ['json', 'rest', 'api', 'oauth']; // 数组 
console. log('tags = ' + JSON.stringify(tags) + '\n'); 


var reqistered = true; // 布尔 值 
console. log('registered = ' + JSON.stringify(reqistered) + '\n'); 


var speaker = { 
firstName: 'Larson', 
lastName: 'Richard', 
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email: 'Larsonrichard@ecratic.com', 
about: 'Incididunt mollit cupidatat magna excepteur do tempor ex non ...', 
company: 'Ecratic', 
tags: ['json', 'rest', 'api', 'oauth'], 
registered: true 
5 


console.log('speaker = ' + JSON.stringify(speaker)); 


在 命令 行 中 用 node 运行 上 述 文件 后 ， 可 以 得 到 以 下 结果 : 


json-at-work => node basic-data-types-stringify.js 
age = 39 





fullName = "Larson Richard" 
tags = ["json", "rest" , "api", "oauth"] 


registered - true 


speaker = ("firstName":"Larson" , "LastName": "Richard", "email":"larsonrichardéecratic.com" , "about" :"Incididunt mollit cupi 
datat magna excepteur do tempor ex non ...","company":"Ecratic" , "tags" : ["json" , "rest" , "api" , "oauth"] , "registered" :true} 
json-at-work => fj 








TI 














对 于 标量 类 型 (数值 、 字 符 串 、 布 尔 值 )，]JSoN.stringify() 并 没有 提供 什么 有 趣 的 功能 。 
但 对 于 speaker 这 样 的 对 象 字 面 量 来 说 ，JSON.stringify() 可 以 生成 一 段 驳 杂 却 合法 的 
JSON 字符 串 ， 因 此 显得 比较 有 用 。]JSoN.stringify() 还 可 以 接受 其 他 参数 ， 从 而 让 序列 
化 操作 变 得 更 加 强大 。 根 据 Mozilla 开发 者 网 络 中 的 JavaScript 指责， 具体 的 语法 如 下 所 示 。 


JSON.stringify(value[, replacer [, space]]) 
参数 列表 如 下 所 示 。 
value ( 必 选 ) 
需要 进行 序列 化 的 JavaScript 值 。 
replacer (可 选 ) 


函数 或 数组 。 如 果 是 函数 ， 则 stringify() 方法 会 为 value 对 象 中 的 每 个 名 称 - 值 对 调 
用 replacer, 










































































space (可 选 ) 
数值 或 字符 串 ， 表 示 缩 进 。 如 果 是 数值 ， 则 表示 每 一 级 缩 进 所 占用 的 空格 数 。 


ffi 2-2 展示 了 对 replacer 和 space 参数 的 使 用 ， 该 示例 优化 了 speaker 对 象 的 显示 ， 同 时 
也 展示 了 对 数据 元 素 的 过 滤 操 作 。 


例 2-2 js/obj-literal-stringify-params.js 

















var speaker = { 
firstName: 'Larson', 
lastName: 'Richard', 
email: 'Larsonrichard@ecratic.com', 
about: 'Incididunt mollit cupidatat magna excepteur do tempor ex non ...', 
company: 'Ecratic', 
tags: ['json', 'rest', 'api', 'oauth'], 
registered: true 


E 





function serializeSpeaker(key, value) { 
return (typeof value --- 'string' || Array.isArray(value)) ? undefined : value; 


// 优化 显示 结果 。 
console.log('Speaker (pretty print):\n' + JSON.stringify(speaker, null, 2) + '\n'); 





// 过 滤 掉 数据 中 的 字符 串 和 数组 ， 优 化 显示 结果 。 
console.log('Speaker without Strings and Arrays:\n' + 
JSON.stringify(speaker, serializeSpeaker, 2)); 











运行 以 上 文件 可 以 得 到 以 下 结果 : 


json-at-work => node obj-literal-stringify-params.js 
Speaker (pretty print): 
{ 





"firstName": "Larson", 
"lastName": "Richard", 
"email": "larsonrichardeecratic. com" , 


"about": "Incididunt mollit cupidatat magna excepteur do tempor ex non ...", 


: "Ecratic", 


"registered": true 


} 


Speaker without Strings and Arrays: 


"registered": true 


json-at-work — | 





的 输出 结果 。 





在 以 上 示例 中 ， 


第 一 次 JSON.stringify() 调用 将 缩 进 设置 为 2 个 空格 ， 从 而 优化 了 JSON 
第 二 次 调用 则 使 用 sertalizeSpeaker() 函数 作为 replacer 参数 (JavaScript 








中 的 函数 可 以 作为 表达 式 以 参数 的 形式 进行 传递 )。serializespeaker() 会 检查 每 个 值 的 类 
型 ， 如 果 类 型 为 字符 串 或 数组 ， 则 返回 undefined， 其 余 情 况 则 返回 值 本 身 。 


对 于 undefined [É, JSON.stringify() 的 处 理 方式 如 下 所 示 : 


。 如 果 undefined 是 对 象 中 的 某 个 字段 的 值 ， 则 序列 化 时 直接 忽略 该 字段 ， 
。 如 果 undefined 是 数组 中 的 一 个 值 ， 则 将 其 转换 为 null。 


2.2.3 ”使 用 toJSON() 进 行 对 和 象 的 序列 化 操作 


正如 你 在 前 





























GH, ISON 序列 化 操作 最 适合 应 用 于 对 象 。 可 以 通过 向 speaker 对 象 中 




















添加 toISON() 方法 来 自 定义 ISON. stringify() 的 输出 结果 ， 如 例 2-3 所 示 。 
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f 2-3 js/obj-literal-stringify-tojson.js 

var speaker = { 
firstName: 'Larson', 
lastName: 'Richard', 
email: 'Larsonrichard@ecratic.com', 
about: 'Incididunt mollit cupidatat magna excepteur do tempor ex non ...', 
company: 'Ecratic', 
tags: ['json', 'rest', 'api', 'oauth'], 
registered: true 

3 

speaker.toJSON = function() { 


return "Hi there!"; 


console.log('speaker.toJSON(): ' + JSON.stringify(speaker, null, 2)); 


序列 化 操作 的 执行 结果 如 下 所 示 : 


json-at-work => node obj-literal-stringify-tojson.js 
speaker.toJSON(): "Hi there!" 





json-at-work => fj 




















如 果 一 个 对 象 拥有 toISON() 方法 ， 则 ISON.stringify() 不 再 试图 将 其 转换 成 字符 串 ， 而 是 
直接 输出 该 对 象 的 toJSON() 方法 所 返回 的 值 。 使 用 toISON() 方法 是 合法 的 ， 但 不 一 定 明智 。 
因为 一 旦 使 用 了 toJSON() 方法 ， 开 发 者 就 必须 自行 承担 对 整个 对 象 结构 的 序列 化 操作 ， 而 
这 完全 违背 了 JSON.stringify() FRIR. XF speaker 这 样 简 单 的 对 象 来 说 ， 可 能 没有 
什么 问题 ， 但 对 于 包含 其 他 对 象 的 复杂 对 象 来 说 ， 相 关 的 序列 化 代码 迟早 会 变 得 非常 庞杂 。 


2.2.4 ”使 用 evatL() 进 行 JSON 的 反 序 列 化 操作 

JavaScript 开发 者 最 初 是 使 用 eval() 函数 来 解析 ISON AY. eval() 可 以 接受 一 个 字符 串 
作为 参数 ， 该 字符 串 可 以 是 一 个 JavaScript 表达 式 、 一 句 JavaScript 语句 ， 或 者 一 连 串 的 
JavaScript 语句 ， 参 见 例 2-4。 









































f| 2-4 js/eval-parse.js 
var x = '( "sessionDate": "2014-10-06T13:30:00.000Z" }'; 


console.log('Parse with eval(): ' + eval('(' + x + ')').sessionDate + '\n'); 


console. log('Parse with JSON.parse(): ' + JSON.parse(x).sessionDate) ; 


运行 以 上 文件 可 以 得 到 以 下 结果 : 


json-at-work => node eval-parse.js 
Parse with eval(): 2014-10-06T13:30:00.000Z 


Parse with JSON.parse(): 2014-10-06T13:30:00.000Z 
json-at-work => 




















在 这 一 示例 中 ，eval() 和 JSON.parse() 的 执行 结果 相同 ， 都 解析 了 日 其 属性。 那么 eval() 
的 问题 在 哪里 ? 例 2-5 展示 了 在 字符 串 中 包含 JavaScript 语句 的 一 个 示例 。 

















例 2-5 js/eval-parse-2.js 
var x = '{ "sessionDate": new Date() }'; 


console.log('Parse with eval(): ' + eval('(' + x + ')').sessionDate + '\n'); 


console.log('Parse with JSON.parse(): 


运行 以 上 代码 可 以 得 到 以 下 结果 : 


tmarrs => node eval-parse-2.js 
Mon Oct 06 2014 20:54:18 GMT-0600 (MDT) 


* JSON.parse(x).sessionDate); 











undefined: 1 
{ "sessionDate": new Date() } 
^ 


SyntaxError: Unexpected token e 
at Object.parse (native) 
at Object.<anonymous> (/Users/tmarrs/projects/json-at-work/chapter-2/js/eval-parse-2.js:5:18) 
at Module. compile (module. js:456:26) 
at Object.Module. extensions..js (module.js:474:10) 
at Module.1load (module. js:356:32) 
at Function.Module._load (module. js:312:12) 
at Function.Module.runMain (module. js:497:10) 
at startup (node. js:119:16) 
at node. js:906:3 
tmarrs => fj 





上 述 示 例 的 文本 参数 中 含有 new Date() 这 一 JavaScript 语句 ， 而 eval() 成 功 执行 了 这 一 


语句 。 与 此 同时 ，JSON.parse() 则 正确 地 拒绝 了 这 一 文本 参数 ， 并 报错 显示 传人 的 ISON 
He 





是 非法 的 。 在 这 一 示例 中 ,嵌入 的 语句 只 是 创建 了 一 个 Date 对 象 ， 并 无 多 少 危害 





; 但 其 


他 上 艇 入 语句 可 能 包含 恶意 代码 ， 而 eval() 会 照样 执行 。 因 此 ， 尽 管 eval() 可 以 用 于 解析 
JSON， 但 该 做 法 一 般 并 不 安全 ， 也 不 合适 。eval() 会 打开 人 允许 任何 JavaScript 表达 式 进 入 
的 后 门 ， 这 会 让 应 用 程序 更 易 受到 攻击 。 由 于 这 一 安全 问题 ， 对 ISON 的 解析 已 经 废弃 了 




















eval() 函数 ， 取 而 代 之 的 是 JSON.parse()。 


2.2.5 ”使 用 JSON.parse() 进 行 JSON 的 反 序列 化 操作 




















我 们 回 到 演讲 者 数据 这 一 示例 ， 例 2-6 展示 了 使 用 JSON.parse() 将 ISON 字符 串 反 序列 化 
为 speaker 对 象 的 情况 。 
例 2-6 js/obj-literal-parse.js 
var json = '(' + // 以 多 行 形式 定义 的 JSON 字 符 串 。 
'""firstName": "Larson",' + 
"LastName": "Richard",' + 
"email": "Larsonrichard@ecratic.com",' + 
about": "Incididunt mollit cupidatat magna excepteur do tempor ex non ...",' + 
"company": "Ecratic",' + 
tags": [' + 
'""json",' + 
""rest",' + 
'""api",' + 
'""oauth"' + 
uso + 
'"registered": true’ + 
"ES 
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// 将 JSON 字 符 串 反 序 列 化 为 speaker 对 象 。 


var speaker = JSON.parse(json); 


// 打印 speaker 对 象 。 


console.log('speaker.firstName = ' + speaker.firstName); 


运行 以 上 文件 可 以 得 到 以 下 结果 : 


json-at-work => node obj-literal-parse.js 
speaker.firstName = Larson 


json-at-work => 








JSON.parse() 接受 一 个 JSON 字符 串 作 为 输入 ， 并 将 其 解析 为 完整 的 JavaScript 对 象 。 在 


以 上 示例 中 ， 解 析 后 即 可 访问 speaker 对 象 的 数据 字段 。 


2.8 JavaScript 对 象 和 JSON 


到 目前 为 止 ， 我 们 展示 了 JavaScript 中 的 核心 数据 类 型 和 简单 的 字面 量 对 象 是 如 何 与 JSON 


进行 交互 的 。 对 于 这 一 过 程 中 所 忽略 的 诸多 细节 ， 接 下 来 将 一 一 深入 阐述 。 在 





























创建 (RK 





例 化 ) JavaScript 对 象 的 几 种 方式 中 ， 对 象 字面 量 形式 与 JSON 对 象 最 为 贴近 ， 因 此 之 后 的 
内 容 也 将 主要 采用 字面 量 形式 来 创建 对 象 。 
例 2-7 再 一 次 展示 了 以 对 象 字面 量 形式 表示 的 speaker 对 象 。 
例 2-7 js/obj-literal.js 
var speaker = { 

firstName: 'Larson', 

lastName: 'Richard', 

email: 'larsonrichard(ecratic.com', 

about: 'Incididunt mollit cupidatat magna excepteur do tempor ex non ...', 


company: 'Ecratic', 
tags: ['json', 'rest', 'api', 'oauth'], 
registered: true, 
name: function() ( 
return (this.firstName + ' ' + this.lastName); 
} 
5 








在 对 象 字面 量 语法 中 ， 对 象 的 属性 (数据 和 函数 ) 会 在 大 括号 中 直接 定义 。 在 以 上 示例 
中 ，speaker 对 象 被 赋值 并 实例 化 。 因 为 对 象 字 面 量 在 组 合 对 象 的 数据 和 功能 上 简洁 而 又 



































不 失 模 块 化 ， 所 以 如 果 在 应 用 程序 中 无 须 再 次 创建 另 一 个 speaker 对 象 实例 时 




















， 则 使 用 对 








象 字面 量 创建 对 象 会 是 一 个 很 不 错 的 方案 。 对 象 字面 量 的 真正 缺陷 在 于 每 次 使 用 字面 量 时 

















只 能 创建 一 个 speaker 实例 ， 同 时 实例 中 的 name() 方法 也 无 法 重用 。 


2.3.1 Node REPL 


到 目前 为 止 ， 我 们 都 是 在 命令 行 中 以 执行 JavaScript 文件 的 方式 来 使 用 Node. 














js。 接 下 来 


我 们 转换 方式 ， 看 看 Node.js 的 解释 器 ， 即 读 取 一 求 值 一 输出 一 循环 (Request-Eval-Print- 
Loop, REPL), REPL 是 一 个 非常 不 错 的 工具 ， 它 提供 了 对 代码 的 即时 执行 与 反馈 ， 方 便 
反复 调试 代码 并 改善 应 用 程序 。 在 Node.js 的 官方 文档 中 可 以 找到 有 关 REPL 的 深入 描述 。 
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E, REPL 也 不 是 完美 的 。 其 中 一 








与 其 他 工具 一 相 





处 地 方 尤其 不 便 : 


json-at-work => node 


>varx=0; 


>vary=x+5; 


> .exit 
json-at-work => fj 








对 于 不 产生 输出 的 每 个 语句 ， 解 释 器 执行 后 将 输 1 














H undefined。 很 多 人 认为 这 一 点 容易 分 








散 注意 力 ， ed vd 了 为 。 


可 以 参见 A2 市 中 的 “改造 REPL 














mynode” 部 分 的 内 容 来 配置 mynode 这 一 命令 行 别名 ， 我 认为 mynode 比 标准 的 Node.js REPL 
更 易 用 。 
言 归 正 传 ， 下 面 来 看 看 speaker 对 象 在 mynode REPL 中 的 使 用 情况 




















json-at-work => mynode 

> var speaker = { 
firstName: 'Larson', 
lastName: 'Richard', 
email: 'larsonrichardeecratic. com' , 
about: 
company: 'Ecratic', 
tags: ['json', 'rest', 
registered: true, 
name: function() { 


'api', 'oauth'], 


'Incididunt mollit cupidatat magna excepteur do tempor ex non ...', 


' 


return (this.firstName + ' ' + this. lastName); 


'Larson' , 
'Richard', 
"Larsonrichard@ecratic.com', 
about: 
company: 
tags: 

[ 'json', 
'rest', 
'api', 
'oauth' 


'Ecratic', 


1, 
registered: true, 
ame: [Function] } 


> 
> speaker .name(); 
"Larson Richard' 
> .exit 
json-at-work => fj 









































'Incididunt mollit cupidatat magna excepteur do tempor ex non ...' 


























从 以 上 的 运行 结果 中 可 以 看 到 ， 我 们 能 够 直接 与 speaker 对 象 交 互 ， 调 用 其 方法 并 在 解释 
器 中 查看 调用 结果 。 
以 下 是 REPL 中 可 以 使 用 的 一 些 命令 。 
.Clear 

清除 当前 REPL 中 的 上 下 文 。 
.break 

返回 REPL 提示 符 。 可 以 在 多 行 语句 中 使 用 此 命令 来 快速 退回 提示 符 。 

在 JavaScript 中 使 用 JSON | 27 





.exit 
退出 当前 REPL. 


.Save 


将 当前 REPL 保存 为 文件 。 
2.3.2 ”有 关 JavaScript 对 象 的 更 多 学 习 资 料 


之 前 的 内 容 忽略 了 JavaScript 面向 对 象 编 程 方面 的 很 多 细节 ， 而 事实 上 在 JavaScript 中 还 存 
在 着 其 他 一 些 与 对 象 进行 交 互 的 方法 。 在 面向 对 象 方面 ， 之 前 的 介绍 只 涉及 了 一 些 皮毛 ， 
这 些 内 容 仅 能 够 让 我 们 在 应 用 程序 中 以 合理 的 方式 使 用 JavaScript 对 象 与 JSON。 完 整 、 深 
入 地 介绍 JavaScript 对 象 超 出 了 本 书 的 探讨 范围 。 如 果 需 要 深入 理解 这 方面 的 知识 ， 可 以 
参考 以 下 高 质量 资源 : 

e JD Isaacks 所 著 的 Learn JavaScript Next (Manning 出 版 社 ) ; 
e Nicholas C. Zakas 所 著 的 《JavaScript 面向 对 象 精 要 》'; 

。 Addy Osmani 所 著 的 《JavaScript 设计 模式 》”。 


2.4 用 模拟 API 进 行 单 元 测试 


了 解 了 如 何 对 speaker 对 象 进行 序列 化 / 反 序 列 化 操作 后 ， 我 们 可 以 运行 一 个 简单 的 服务 
器 端 单元 测试 程序 ， 以 便 对 json-server 提供 的 模拟 API 进行 测试 。 而 在 之 后 所 创建 的 小 
Web 应 用 程序 中 ， 该 模拟 API 也 会 得 到 使 用 。 


2.4.1 单元 测试 风格 一 一 TDD 和 BDD 


测试 驱动 开发 (Test-Driven Development, TDD) 是 使 用 单元 测试 来 驱动 开发 工作 的 一 种 
开发 策略 。 其 典型 工作 流程 如 下 。 


(1) 编写 一 些 测 试用 例 。 
(2) 运行 测试 用 例 ， 因 为 还 没有 任何 实际 代码 ， 所 以 运行 结果 会 失败 。 
(3) 编写 实际 代码 ， 可 以 通过 测试 就 好 。 

(4) 重 构 实际 代码 ， 改 进 代 码 的 设计 与 灵活 性 。 

(5) 重新 运行 测试 ， 修 复出 现 的 问题 ， 直 至 所 有 测试 用 例 通 过 。 


TDD 风格 的 单元 测试 呈现 出 过 程式 的 特点 。 


行为 驱动 开发 (Behavior-Driven Development, BDD) 是 一 种 根据 验收 标准 和 期 望 结果 来 
测试 用 户 故 事 的 开发 策略 。BDD 风格 的 测试 用 例 读 起 来 和 普通 的 句子 相同 ， 例 如 ,， “演讲 
者 应 当 在 30 天 之 内 从 会 议 方 收 到 他 们 的 报酬 "。 如 需 了 解 更 多 有 关 BDD 的 信息 ， 可 以 参 
75 Dan North 的 一 篇 非常 不 错 的 文章 “Introducing BDD”, A AVA BDD 只 是 TDD 的 
一 种 改进 。 我 倾向 于 同意 这 一 观点 ， 因 为 开发 者 在 BDD 过 程 中 会 遵循 和 TDD 一 样 的 工作 


J H 
流程 。 
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ik 1: 此 书 已 由 
注 2: 此 书 已 


民 邮 电 出 版 社 出 版 。 一 一 编者 注 
民 邮 电 出 版 社 出 版 。 一 一 编者 注 

































































BDD 和 TDD 都 是 可 靠 的 开发 策略 ， 并 且 可 以 结合 起 来 使 用 ， 从 而 为 应 用 程序 构造 健壮 的 
测试 套件 。 本 章 的 单元 测试 中 的 断言 将 使 用 BDD 风格 编写 。 


2.4.2 ”使 用 Mocha 和 Chai 即 可 完成 单元 测试 

接 下 来 的 服务 器 端 单元 测试 将 会 用 到 以 下 两 个 工具 。 

Mocha 
Mocha 是 一 个 JavaScript 单元 测试 框架 ， 在 Node.js FID Tat PHOS iT. AS A E 
Node.js 项 目 中 用 命令 行 的 方式 使 用 Mocha， 并 添加 功能 来 实现 基于 ISON 的 API 测试 。 
如 需 了 解 更 多 有 关 Mocha 的 细节 ， 可 访问 其 官方 网 站 。 

Chai 
Chai 是 一 个 断言 库 ， 用 于 在 JavaScript 测试 框架 (如 本 节 中 的 Mocha) 中 添加 更 丰富 的 
新 言语 句 ， 从 而 对 框架 形成 有 益 的 补充 。Chai 允许 开发 者 以 TDD 或 者 BDD 的 风格 来 
编写 测试 。 本 章 的 测试 用 例 将 使 用 expect (BDD) 的 断言 风格 ， 但 你 也 可 以 尝试 一 下 
should (BDD) 或 者 assert (TDD) 的 断言 风格 。 总 之 ， 采 用 自己 觉得 顺手 的 风格 即 
可 。 如 需 了 解 更 多 有 关 Chai 的 细节 ， 可 访问 其 官方 网 站 。 


2.4.8 ”设置 单元 测试 环境 

在 进一步 深入 前 ， 需 要 确保 已 设置 好 测试 环境 。 如 尚未 安装 Node.js， 可 参考 A.2 节 和 
A.2.5 节 的 内 容 来 执行 Node.js 的 安装 操作 。 如 需 依 照 本 节 的 描述 运行 代码 示例 中 的 项 目 ， 
可 使 用 cd 命令 切换 到 chapter-2/speakers-test 目录 ， 并 执行 以 下 命令 来 安装 项 目 依 赖 : 


npm install 


如 需 手 动 创建 本 节 中 的 Nodejs 项 目 ， 可 参考 本 书 在 GitHub 上 的 相关 指导 步 又 。 
























































2.4.4 Unirest 


本 节 的 单元 测试 需要 通过 HTTP 来 调用 API， 因 此 我 们 会 在 编写 测试 的 过 程 中 使 用 
Unirest, Unirest 是 Mashape 团队 开发 的 一 款 开 源 跨 平台 的 REST 客 户 端 工具 ， 洒 盖 
JavaScript, Node.js, Ruby on Rails 和 Java 等 多 种 编程 语言 。Unirest 简单 易 用 ， 在 对 REST 
API 进行 HTTP 调用 的 所 有 客户 端 代码 中 都 能 很 好 地 工作 ， 与 此 同时 ， 它 还 非常 适用 于 单 
元 测试 。 对 于 测试 套件 中 的 HTTP 配置 信息 CURT, HTTP 头 部 等 )， 使 用 Unirest 可 以 做 
到 一 次 配置 、 多 次 调用 ， 因 此 有 利于 编写 更 加 整洁 的 单元 测试 用 例 。 如 需 了 解 Unirest 的 
详细 文档 ， 可 访问 其 官方 网 站 。 

跨 平 台 性 与 概念 和 调用 方法 在 多 种 编程 语言 实现 间 的 高 度 相 似 ， 使 得 Unirest 成 为 了 非常 
不 错 的 选择 。 除 此 之 外 ， 也 存在 其 他 一 些 优秀 的 HTTP 类 库 ， 有 Web 的、 移动 端 的 ， 以 及 
基于 Java 的 (4l Apache 的 HttpClient， 不 过 作为 多 门 编程 语言 的 开发 者 ， 我 更 倾向 于 使 用 
Unirest。 值 得 一 提 的 是 ，Unirest 不 仅 适 用 于 单元 测试 ， 作 为 HTTP 客户 端 领域 的 API 封装 
程序 ，Unirest 有 着 广泛 的 应 用 )。 
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2.4.5 测试 数据 


本 节 将 使 用 第 1 章 中 提供 的 演讲 者 数据 作为 测试 数据 ， 并 将 其 部 署 为 RESTful API。 与 第 
1 章 相 同 ， 我 们 将 使 用 json-server 这 个 Node.js 模块 把 data/speakers.json 文件 部 署 为 Web 
API。 如 需 了 解 有 关 安 装 json-server 的 信息 ， 可 参考 A.2.5 节 中 的 内 容 。 


以 下 是 在 本 地 机 器 中 使 用 5000 端口 运行 json-server 的 步骤 : 


cd chapter-2/data 





json-server -p 5000 ./speakers.json 


2.4.6 ”对 演讲 者 数据 进行 单元 测试 
例 2-8 中 的 单元 测试 展示 了 如 何 使 用 Unirest 向 json-server 提供 的 模拟 API 发 起 调用 。 
例 2-8 speakers-test/speakers-spec.js 


'use strict'; 








var expect = require('chai').expect; 
var unirest - require('unirest'); 


var SPEAKERS ALL URI = 'http://localhost:5000/speakers' ; 


describe('speakers', function() { 
var req; 


beforeEach(function() ( 
req - unirest.get(SPEAKERS ALL URI) 
.header('Accept', 'application/json'); 


H; 


it('should return a 200 response', function(done) { 
req.end(function(res) { 
expect(res.statusCode).to.eql(200); 
expect(res.headers['content-type']).to.eql( 
'application/json; charset=utf-8'); 


done(); 
25 
H); 


it('should return all speakers', function(done) { 
req.end(function(res) { 
var speakers = res.body; 
var speaker3 = speakers[2]; 


expect(speakers.length).to.eql(3); 
expect(speaker3.company).to.eql('Talkola'); 
expect(speaker3.firstName).to.eql('Christensen'); 
expect(speaker3.lastName).to.eql('Fisher'); 
expect(speaker3.tags).to.eql([ 

'Java', 'Spring', 

'Maven', 'REST' 
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H); 

该 单元 测试 中 进行 了 以 下 操作 。 

。 测试 代码 在 Mocha 的 beforeEach() 方法 中 对 unirest AY URI 和 Accept 头 部 进行 配置 ， 
从 而 避免 了 配置 代码 的 重复 。 在 describe 语句 所 定义 的 范围 内 ，Mocha 会 在 执行 每 个 
测试 用 例 (HI it 语句 ) 前 先 运行 一 次 beforeEach() 方法 。 

。 测试 代码 中 的 should return all speakers 测试 用 例 最 有 意思 ， 其 工作 机 制 如 下 。 

— req.end() 异步 地 执行 Unirest 中 的 GET 请 求 ， 并 使 用 匿名 函数 来 处 理 API 调用 所 返 

的 HTTP 响应 (res), 

- 测试 用 例 从 HTTP 响应 体 (res.body) 中 提取 speakers 对 象 。 此 时 ，Unirest 已 经 自 

动 解析 了 API 所 返回 的 JSON, 并 以 对 象 字面 量 的 形式 转换 成 对 应 的 JavaScript 对 象 。 

- 测试 用 例 使 用 Chai 中 BDD 风格 的 expect 断言 语句 来 检查 预期 结果 。 
+ 存在 3 个 speaker。 

4 第 三 个 speaker 的 company, firstName, LastName 和 tags 字段 与 speakers.json X: 

件 中 的 值 保 持 一 致 。 

可 以 新 开 命令 行 终端 并 执行 以 下 命令 来 运行 上 面 的 单元 测试 程序 : 


cd chapter-2/speakers-test 
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npm test 


运行 后 可 观察 到 以 下 结果 : 


json-at-work => npm test 
> mocha test 


speakers 
V should return a 200 response 
V should return all speakers 


2 passing 


2.5 ”搭建 小 型 Web 应 用 程序 

在 介绍 了 如 何 对 speaker 对 象 进行 JSON 序列 化 / 反 序 列 化 操作 ， 以 及 如 何 对 json-server 
所 提供 的 模拟 API 进行 单元 测试 后 ， 现 在 是 时 候 搭 建 一 个 简单 的 web 应 用 将 API 数据 呈 
现 给 用 户 了 。 
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这 一 Web 应 用 的 开发 过 程 分 为 3 个 阶段 。 

。 第 1 阶段 : EH Yeoman 生成 一 个 基本 的 Web MH. 

。 第 2 阶段 : 使 用 jQuery 发 起 HTTP 请 求 。 

。 第 3 阶段 : 在 模板 中 使 用 json-server 提供 的 模拟 API 数据 。 








2.5.1 Yeoman 


Yeoman 与 Java 社区 中 的 Gradle, Maven 以 及 Ruby on Rails 比较 像 ， 它 提供 了 一 种 简单 
的 方式 来 快速 创建 Web 应 用 程序 ， 从 而 简化 开发 者 的 工作 流程 。 本 节 将 使 用 Yeoman 来 
搭建 、 开 发 并 运行 示例 应 用 程序 。 如 需 安 装 (依赖 Node.js 的 ) Yeoman， 可 参考 A.2.4 ip 
的 指导 步骤 。 


Yeoman 可 以 提供 以 下 功能 : 


。 创建 开发 环境 ; 

。 运行 应 用 程序 ; 

。 保存 代码 改动 后 自动 刷新 浏览 器 ， 

。 管理 包 依赖 关系 ; 

。 压缩 应 用 程序 的 代码 并 打包 ， 以 便于 部 署 。 

Yeoman 遵循 “约定 优 于 配置 ”的 理念 : 

。 自动 化 搭建 ， 

。 可 以 工作 就 好 ; 

。 使 用 标准 目录 结构 ; 

。 提供 依赖 管理 ; 

。 预 设 合理 的 默认 值 ; 

。 鼓励 最 佳 实践 ， 

。 基于 工具 的 开发 流程 (如 在 测试 、 代 码 检 查 、 运 行 和 打包 过 程 中 使 用 专业 的 工具 )。 
如 需 了 解 更 多 有 关 Yeoman 的 信息 ， 可 参考 以 下 Yeoman 教程 : 
。 使 用 Yeoman 快速 搭建 Web 应 用 程序 ; 

。 使 用 Yeoman 工作 流 构建 应 用 程序 。 

1. Yeoman 工 具 集 

Yeoman 由 以 下 工具 组 成 。 





















































快速 搭建 

可 以 使 用 Yo 命令 来 生成 应 用 程序 的 目录 结构 及 Grunt/Gulp/Bower 的 配置 文件 。 
构建 

可 以 使 用 Gulp 或 Grunt 来 构建 、 运 行 、 测 试 和 打包 应 用 程序 。 
&, m 


可 以 使 用 Bower 或 npm 来 管理 和 下 载 包 依赖 。 





























虽然 Grunt 是 一 个 可 靠 的 构建 工具 ，npm 也 是 一 个 非常 优秀 的 包 管 理 器 ， 但 因为 Yeoman 
的 Web 应 用 程序 生成 器 中 使 用 了 Gulp 和 Bower， 所 以 我 们 也 将 在 本 市 示例 中 使 用 Gulp 和 


Bower。 


2. Yeoman 生 成 器 
Yeoman 使 用 生成 器 来 快速 构建 项 目 。 每 个 生成 器 都 可 以 创建 一 个 预先 配置 好 的 模板 应 用 
程序 。 对 于 目前 已 有 的 上 千 个 生成 器 ，Yeoman 官方 提供 了 一 份 完 整 的 列表 。 


2.5.2 第 1 阶段 : 使 用 Yeoman 生 成 Web 应 用 程序 

首先 ， 我 们 创建 一 个 不 包含 任何 实际 功能 的 简单 应 用 程序 ， 并 将 演讲 者 数据 硬 编码 到 一 
个 表格 中 。 我 们 会 在 第 2 和 第 3 阶段 中 添加 真实 的 演讲 者 数据 。 安 装 好 Yeoman 后 ， 我 们 
将 使 用 generator-webapp 生成 器 来 创建 开 箱 即 用 的 Web 应 用 程序 ， 该 应 用 程序 自 带 网 页 、 
CSS 样式 、Bootstrap 4、jQuery、Mocha 和 Chai, 


如 需 手 动 创建 本 节 中 的 Yeoman 项 目 ， 可 参考 本 书 在 GitHub 上 的 相关 指导 步骤 。 如 需 依 
照 本 节 的 描述 运行 代码 示例 中 的 Yeoman 项 目 ， 可 使 用 cd 命令 切换 到 chapter-2/speakers- 
web-1 目录 。 无 论 何 种 形式 ， 都 可 以 使 用 以 下 命令 来 启动 应 用 程序 : 


gulp serve 


这 一 命令 可 以 启动 本 地 Web 服务 器 ， 并 在 默认 浏览 器 中 打开 首页 (index.html)。 可 以 通过 
http://localhost:9000 访问 到 以 下 页 面 ， 如 图 2-1 所 示 。 















































© ®© / B speaker web 1 x 








C 合 | © localhost:9000 


speaker web 1 | Home | About Contact 


Allo, 'Allo! 


Always a pleasure scaffolding your apps. 


HTML5 Boilerplate 

HTML5 Boilerplate is a professional front- 
end template for building fast, robust, and 
adaptable web apps or sites. 


Bootstrap 

Sleek, intuitive, and powerful mobile first 
front-end framework for faster and easier 
web development. 











2-1: FB Yeoman 生成 的 基础 Web 应 用 程序 
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值得 注意 的 是 ， 如 果 应 用 程序 保持 运行 ， 那 么 保存 代码 修改 后 ， 应 用 程序 会 使 用 LiveReload 
来 自动 更 新 页 面 上 的 相关 内 容 。 


使 用 Yeoman 的 generator-webapp 生成 器 创建 好 初始 应 用 程序 后 ， 就 可 以 对 该 应 用 程 
序 进行 定制 了 。 首 先 ， 可 以 修改 index.html 页 面 中 的 标题 、 页 眉 和 显示 屏 组 件 ( 即 移 除 
“Splendid!” 按 钮 )， 如 例 2-9 所 示 。 


fj 2-9 speakers-web-1/app/index.html 
<!doctype html» 


«html lang-""s 
«head» 

















«title»JSON at Work - MyConference</title> 


</head> 
<body> 


<div class="header"> 


<h3 class="text-muted">JSON at Work - Speakers</h3> 
</div> 


<div class="jumbotron"> 

«h1 class="display-3">Speakers</hi> 

«p class="lead">Your conference lineup.«/p» 
</div> 


</body> 
</htmL> 


然后 在 index.html 文件 中 以 硬 编码 的 方式 添加 演讲 者 数据 表格 ， 如 例 2-10 所 示 。 


例 2-10  speakers-web-l/app/index.html 
<!doctype html» 


«html lang-""s 








«body» 


«table class="table table-striped"> 
<thead> 
<tr> 
<th>Name</th> 
<th>About</th> 
<th>Topics</th> 
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</tr> 


</thead> 
<tbody id="speakers-tbody"> 


<tr> 
<td>Larson Richard</td> 
<td>Incididunt mollit cupidatat magna excepteur do tempor ... 
</td> 
«td»JavaScript, AngularJS, Yeoman</td> 
</tr> 
<tr> 
<td>Ester Clements</td> 
<td>Labore tempor irure adipisicing consectetur velit. ... 
</td> 
<td>REST, Ruby on Rails, APIs</td> 
</tr> 
<tr> 
<td>Christensen Fisher</td> 
<td>Proident ex Lorem et Lorem ad. Do voluptate officia ... 
</td> 
<td>Java, Spring, Maven, REST</td> 
</tr> 


</tbody> 
</table> 


</body> 


</html> 








这 样 就 可 以 实现 一 个 显示 示例 演讲 者 数据 的 Web 应 用 程序 ， 如 图 2-2 所 示 。 














eoo 


É& JSON at Work - MyConference x 





Q (Y | © localhost:9000 * 


Speakers 


Your conference lineup. 


Name About Topics 

Larson Incididunt mollit cupidatat magna excepteur do tempor ex JavaScript, 

Richard non eiusmod magna exercitation proident nisi non. Sunt ad AngularJS, 
consequat eu non esse excepteur. Veniam quis Lorem ea Yeoman 


labore ullamco veniam nisi do sunt. Nisi irure sit qui irure 
mollit ad aliquip non culpa sint reprehenderit ullamco. 


Ester Labore tempor irure adipisicing consectetur velit. Ipsum REST, 
Clements Lorem non mollit aliquip. Fugiat est irure quis laboris minim Ruby on 
anim esse fugiat et culpa exercitation. Dolor cillum excepteur Rails, APIs 
officia Lorem ullamco magna et cupidatat dolor incididunt 
occaecat adipisicing consectetur in. Ullamco ullamco 
commodo nulla eiusmod. Lorem Lorem non sunt laboris ut et 
elit mollit deserunt nostrud est et id adipisicing. 


Christensen Proident ex Lorem et Lorem ad. Do voluptate officia minim in Java, 
Fisher nisi ut sit nisi ex eu nostrud do ut. Aute ad dolor tempor Spring, 
dolor aute nisi deserunt deserunt ut deserunt cillum quis. Maven, 
Ipsum nulla sit reprehenderit consequat incididunt incididunt REST 
dolore et magna aliquip ut ex. Cupidatat exercitation ipsum 
dolore nisi incididunt anim est. Culna veniam ut excenteur 








图 2-2. index.html 中 的 示例 演讲 者 数据 
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以 下 是 generator -webapp 生成 的 应 用 程序 中 比较 关键 的 文件 和 目录 。 


。 Uu e E 
index.html 为 应 用 程序 的 主页 。 
一 images/ 目录 包含 应 用 程序 所 使 用 的 图 片 文件 。 
— scripts/ 目录 包含 应 用 程序 所 使 用 的 JavaScript 等 脚本 文件 。 
€ main.js 是 应 用 程序 的 主 JavaScript 文件 。 我 们 将 在 第 2 阶段 中 详细 介绍 此 文件 。 
— styles/ 目录 包含 CSS 等 样式 文件 。 
。 bower_components/ 目录 包含 由 Bower 所 安装 的 项 目 依赖 : Bootstrap, jQuery, Mocha 
和 Chai。 
。 node modules/ 目录 包含 Gulp 等 Node.js 所 需要 的 项 目 依 赖 。 
。 test/ 目录 包含 测试 框架 所 使 用 的 测试 用 例 。 本 例 使 用 的 测试 工具 为 Mocha 和 Chai. 
* gulpfile.js 是 Gulp 的 构建 脚本 文件 ， 用 于 构建 和 运行 应 用 程序 。 
。 package.json 是 Node.js 用 于 管理 依赖 的 配置 文件 ，Gulp 则 会 使 用 这 些 依赖 来 运行 项 目 
脚本 。 
。 dist/ 目录 包含 由 gulp build 命令 所 构建 的 文件 。 


关于 使 用 generator-webapp 生成 的 应 用 程序 ， 以 下 是 一 些 有 用 的 重要 命令 





















































Ctrl-C 
关闭 Web 服务 器 ， 退 出 应 用 程序 。 
gulp lint 


使 用 Lint 对 应 用 程序 中 的 JavaScript 文件 进行 语法 检查 。 
gulp +serve:test 


对 Web 应 用 程序 进行 测试 。 在 本 例 中 ， 测 试 程序 会 在 PhantomJS 环境 中 使 用 Mocha 和 
Chai。 








gulp build 
对 应 用 程序 进行 构建 、 打 包 以 方便 部 署 。 
gulp clean 
清除 测试 和 构建 应 用 程序 过 程 中 所 生成 的 文件 。 


可 以 在 命令 行 中 输入 gulp --tasks 来 获取 完整 的 命令 列表 。 
开始 第 2 阶段 的 工作 前 ， 确 保 关 闭 之 前 所 启动 的 Web 应 用 程序 。 


2.5.8 第 2 阶段 : 使 用 jQuery 发 起 HTTP 请 求 


第 1 阶段 中 开发 的 Web 应 用 程序 以 硬 编码 的 方式 显示 演讲 者 数据 ， 而 现在 是 时 候 添 加 “ 真 
实 的 ”内 容 和 功能 


有 具体 工作 分 为 以 下 3 个 步骤 。 


(1) 重 构 首页 代码 ， 移 除 硬 编码 的 演讲 者 数据 。 
(2) 添 加 单独 的 ISON 文件 来 保存 演讲 者 数据 。 




















(3) 使 用 jQuery 将 JSON 文件 中 的 演讲 者 数据 显示 在 页 面 上 。 
如 需 自 行 搭建 第 2 阶段 中 的 Yeoman 项 目 ， 可 以 执行 以 下 操作 。 
。 参考 本 书 在 GitHub 上 的 相关 指导 步骤 。 
。 记得 将 第 1 阶段 中 修改 后 的 app/index.html 文件 复制 到 项 目 中 。 
如 需 依照 本 节 的 描述 运行 代码 示例 中 的 Yeoman 项 目 ， 可 以 使 用 cd 命令 切换 到 chapter-2/ 
speakers-web-2 目录 。 无 论 何 种 形式 ， 都 可 以 使 用 以 下 命令 来 启动 应 用 程序 : 
gulp serve 
和 第 1 阶段 一 样 ， 这 一 命令 可 以 启动 本 地 Web 服务 器 。 可 通过 http:Wlocalhost:9000 访问 主 
页 ， 如 图 2-3 所 示 。 








@ © © / B JsoNat Work - MyConference x CN 


© € | © localhost:9000 $5 


Speakers 


Your conference lineup. 





Name About Topics 

Larson Incididunt mollit cupidatat magna excepteur do tempor ex JavaScript, 

Richard non eiusmod magna exercitation proident nisi non. Sunt ad AngularJS, 
consequat eu non esse excepteur. Veniam quis Lorem ea Yeoman 


labore ullamco veniam nisi do sunt. Nisi irure sit qui irure 
mollit ad aliquip non culpa sint reprehenderit ullamco. 


Ester Labore tempor irure adipisicing consectetur velit. Ipsum REST, 
Clements Lorem non mollit aliquip. Fugiat est irure quis laboris minim Ruby on 
anim esse fugiat et culpa exercitation. Dolor cillum excepteur Rails, APIs 
officia Lorem ullamco magna et cupidatat dolor incididunt 
occaecat adipisicing consectetur in. Ullamco ullamco 
commodo nulla eiusmod. Lorem Lorem non sunt laboris ut et 
elit mollit deserunt nostrud est et id adipisicing. 


Christensen Proident ex Lorem et Lorem ad. Do voluptate officia minim in Java, 
Fisher nisi ut sit nisi ex eu nostrud do ut. Aute ad dolor tempor Spring, 
dolor aute nisi deserunt deserunt ut deserunt cillum quis. Maven, 
Ipsum nulla sit reprehenderit consequat incididunt incididunt REST 
dolore et magna aliquip ut ex. Cupidatat exercitation ipsum 
dolore nisi incididiint anim est Culna veniam ut excenter 











图 2-3: 示例 演讲 者 数据 
和 之 前 看 到 的 结果 一 样 ， 主 页 (index.html) 在 表格 中 展示 了 硬 编码 的 演讲 者 数据 。 请 保持 
应 用 程序 运行 ， 以 观察 代码 修改 的 结果 。 


接 下 来 ， 我 们 移 除 表格 内 容 中 所 有 行 的 数据 。 修 改 后 演讲 者 表格 的 HTML 代码 如 例 2-11 
所 示 。 
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例 2-11 speakers-web-2/app/index.html 
<!doctype html» 


«html lang-""s 


«body» 


«table class="table table-striped"> 
<thead> 
<tr> 
<th>Name</th> 
<th>About</th> 
<th>Topics</th> 
</tr> 
</thead> 
<tbody id="speakers-tbody"> 
</tbody> 
</table> 


</body> 
</html> 


例 2-11 中 包含 了 一 个 只 有 标题 行 的 空 表格 。 该 表格 使 用 Bootstrap 的 table-striped CSS 
类 让 内 容 行 呈现 出 灰白 相间 的 效果 。 注 意 ， 用 于 存储 表格 内 容 的 <tbody> 元 素 定义 了 名 为 
speakers-tbody 的 ID， 而 jQuery 就 是 通过 这 个 ID 来 动态 添加 表格 行 的 。 

接 下 来 ， 我 们 需要 在 一 个 单独 的 JSON 文件 中 存储 演讲 者 数据 。 参 见 从 /chapter-2/data/ 
speakers.json 处 复制 而 来 的 带 有 演讲 者 数据 的 /speakers-web-2/app/data/speakers.json 文件 。 
最 后 ， 修 改 app/scripts/main.js 文件 ， 使 用 jQuery 将 app/data/speakers.json 文件 中 的 数据 添 
加 到 演讲 者 表格 中 ， 如 例 2-12 所 示 。 
例 2-12 speakers-web-2/app/scripts/main.js 


"use strict'; 
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console.log('Hello JSON at Work!'); 


$(document).ready(function() { 


function addSpeakersjQuery(speakers) { 
$.each(speakers, function(index, speaker) { 
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var tbody = $('#speakers-tbody'); 

var tr = $('<tr></tr>'); 

var nameCol = $('<td></td>'); 

var aboutCol = $('<td></td>'); 

var topicsCol = $('<td></td>'); 
nameCol.text(speaker.firstName + ' ' + speaker.lastName); 
aboutCol.text(speaker . about); 
topicsCol.text(speaker.tags.join(', ')); 


tr.append(nameCol); 
tr.append(aboutCol); 
tr.append(topicsCol); 
tbody .append(tr); 
IDE 
} 


$.getJSON('data/speakers.json', 
function(data) { 
addSpeakersjQuery(data.speakers); 


p); 


在 以 上 示例 中 ， 前 端 代码 包含 在 jQuery 的 $(document).ready() 里 ， 因 此 会 等 包括 DOM 
在 内 的 整个 页 面 完 全 加 载 后 才 运行 。 代 码 中 的 $.getISON() 是 一 个 jQuery 方法 ， 用 于 向 某 
个 URL Riž HTTP GET 请 求 ， 并 将 ISON 响应 转换 为 JavaScript 对 象 。 因 为 示例 中 的 app/ 
data/speakers.json 文件 被 部 署 为 Web 应 用 程序 的 一 部 分 ， 所 以 可 以 通过 HTTP 协议 以 URL 
的 形式 访问 。 最 终 ， 获 得 演讲 者 数据 后 ，$.getJSON() 的 回调 函数 会 将 填充 演讲 者 表格 的 
工作 交 给 addSpeakersjQuery() 函数 来 进行 。 


addSpeakersjQuery() 函数 使 用 jQuery 提供 的 .each() 方法 来 遍历 包含 演讲 者 数据 的 数 
组 。.each() 国 数 进 行 的 工作 包括 以 下 几 项 : 


。 使 用 index.html 文件 中 的 speakers-tbody ID 来 找到 演讲 者 表格 中 的 <tbody> 元 素 ; 
。 使 用 speaker 对 象 中 的 数据 来 填充 <tr> 和 <td> 元 素 ， 从 而 创建 相应 的 表格 行 及 其 列 ; 
。 将 新 创建 的 表格 行 添加 到 <tbody> 元 素 中 。 


如 需 了 解 更 多 有 关 jQuery 的 getJSON() 函数 的 信息 ， 可 参考 jQuery 官方 文档 。 
如 有 果 之 前 一 直 保 持 应 用 程序 运行 ， 那 么 现在 可 以 看 到 如 图 2-4 所 示 的 截图 。 
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CO | © localhost:9000 P 


Speakers 


Your conference lineup. 


Name About Topics 

Larson Incididunt mollit cupidatat magna excepteur do tempor ex JavaScript, 

Richard non eiusmod magna exercitation proident nisi non. Sunt ad AngularJS, 
consequat eu non esse excepteur. Veniam quis Lorem ea Yeoman 


labore ullamco veniam nisi do sunt. Nisi irure sit qui irure 
mollit ad aliquip non culpa sint reprehenderit ullamco. 


Ester Labore tempor irure adipisicing consectetur velit. Ipsum REST, 
Clements Lorem non mollit aliquip. Fugiat est irure quis laboris minim Ruby on 
anim esse fugiat et culpa exercitation. Dolor cillum excepteur Rails, APIs 
officia Lorem ullamco magna et cupidatat dolor incididunt 
occaecat adipisicing consectetur in. Ullamco ullamco 
commodo nulla eiusmod. Lorem Lorem non sunt laboris ut et 
elit mollit deserunt nostrud est et id adipisicing. 


Christensen Proident ex Lorem et Lorem ad. Do voluptate officia minimin Java, 
Fisher nisi ut sit nisi ex eu nostrud do ut. Aute ad dolor tempor Spring, 
dolor aute nisi deserunt deserunt ut deserunt cillum quis. Maven, 
Ipsum nulla sit reprehenderit consequat incididunt incididunt REST 
dolore et magna aliquip ut ex. Cupidatat exercitation ipsum 
dolore nisi incididunt anim est. Culpa veniam ut excepteur 











& 2-4: 用 jQuery 和 JSON 文件 所 得 到 的 示例 演讲 者 数据 结 


正如 所 预期 的 那样 ， 页 面 看 上 去 和 本 节 刚 开始 时 一 模 一 样 。 但 与 一 开始 不 同 的 是 ， 重 构 后 

移 除 了 页 面 中 硬 编码 的 演讲 者 数据 ， 并 以 HTTP 请 求 取而代之 。 到 目前 为 止 ， 我 们 已 经 

了 一 个 真正 的 Web ARERR: 动态 填充 页 面 。 但 这 一 雏形 依旧 存在 以 下 不 足 。 

。 JSON 数据 由 Web 应 用 程序 中 的 静态 文件 所 提供 ， 我 们 则 希望 从 RESTful API 中 来 获取 
数据 。 

e JavaScript 代码 与 页 面 中 的 HTML 元 素 耦 合 过 紧 ， 我 们 则 希望 减少 HIML fil DOM 的 
操作 。 


开始 第 3 阶段 的 工作 前 ， 确 保 关 闭 了 之 前 所 局 动 的 Web 应 用 程序 。 


2.5.4 第 3 阶段 : 在 模板 中 使 用 模拟 API 所 提供 的 演讲 者 数据 


第 2 阶段 中 开发 的 Web 应 用 程序 通过 发 送 HTTP 请 求 将 ISON 文件 中 的 演讲 者 数据 填充 到 

主页 上 ， 接 下 来 的 内 容 则 会 从 json-server 所 提供 的 模拟 API 中 来 获取 数据 。 除 此 之 外 ， 
seers JavaScript 代码 ， 移 除 有 关 HTML 和 DOM 的 操作 ， 并 以 Mustache 这 一 外 部 
模板 取而代之 。 


有 具体 工作 分 为 以 下 2 F. 













































































(D 修改 HTTP 请 求 ， 将 请 求 发 送 至 由 json-server 所 提供 的 URI 中。 
(2) 使 用 Mustache 模板 ， 移 除 JavaScript 代码 中 的 HTML 和 DOM 操作 。 
如 需 自 行 搭建 第 3 阶段 中 的 Yeoman 项 目 ， 可 以 执行 以 下 操作 。 


。 参考 本 书 在 GitHub 上 的 相关 指导 步骤 。 
。 记得 将 第 2 阶段 中 修改 的 以 下 文件 复制 到 项 目 中 。 
— app/index.html 








— app/scripts/main.js 


如 需 依 照 本 节 的 描述 运行 代码 示例 中 的 Yeoman 项 目 ， 可 以 使 用 ed 命令 切换 到 chapter-2/ 
speakers-web-3 目录 。 


接 下 来 ， 我 们 修改 main.js 中 的 HTTP 请 求 ， 将 请 求 发 送 至 由 json-server 所 提供 的 模拟 演 
讲 者 数据 API 中 ， 如 例 2-13 所 示 。 


例 2-13  speakers-web-3/app/scripts/main.js 


$.getJSON( 'http://localhost:5000/speakers', 
function(data) { 
addSpeakers jQuery(data); 
} 
); 





修改 后 ， 代 码 将 调用 由 json-server 所 提供 的 模拟 演讲 者 数据 API。 值 得 注意 的 是 ， 因 为 
json-server 所 提供 的 数据 不 包含 speakers 字段 ， 所 以 传 入 addSpeakersjQuery() 的 参数 是 
data 而 不 是 第 2 阶段 中 的 data. speakers。 


运行 Web 应 用 程序 前 ， 打 开 一 个 新 的 命令 行 窗口 ， 在 5000 端口 上 运行 json-server 


cd chapter-2/data 























json-server -p 5000 ./speakers.json 
然后 在 另 一 个 新 的 命令 行 窗口 中 运行 以 下 命令 ， 以 启动 Web 应 用 程序 : 

gulp serve 
与 第 1、 第 2 阶段 一 样 ， 这 一 命令 会 启动 本 地 Web 服务 器 。 可 以 在 浏览 器 中 通过 访问 
http://localhost:9000 看 到 与 之 前 一 样 的 演讲 者 数据 。 虽 然 结果 相同 ， 但 因为 使 用 的 数据 来 


自 于 API 而 不 是 静态 文件 ， 所 以 Web 应 用 程序 的 质量 比 之 前 要 好 得 多 。 请 保持 应 用 程序 
运行 ， 以 观察 代码 修改 的 结果 。 


接 下 来 我 们 重 构 JavaScript 代码 ， 移 除 其 中 的 HTML 和 DOM 操作 并 使 用 Mustache 模板 。 
Mustache 号 称 自己 提供 的 是 无 逻辑 模板 ， 即 在 使 用 JavaScript 等 语言 来 生成 HTML 的 过 程 
中 无 须 使 用 控制 语句 (for、if 等 )。Mustache 支持 多 种 编程 语言 。 


例 2-14 就 是 将 演讲 者 数据 转换 成 HTML 内 容 的 Mustache 模板 。 
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f| 2-14 /app/templates/speakers-mustache-template.html 
<!-- 


[speakers-mustache-tempLate. html] 

此 为 应 用 程序 首次 启动 时 ， 演讲 者 数组 数据 所 使 用 的 模板 

<script id="speakerTemplate" type="text/html"> 
{{#.}} 


<tr> 
<td>{{firstName}} {{lastName}}</td> 
<td>{{about}}</td> 
<td>{{tags}}</td> 
</tr> 
{{/.}} 


</script> 

以 下 是 对 这 一 示例 的 一 些 解释 。 

。 模板 以 外 部 文件 的 形式 存在 ， 将 HTML 与 JavaScript 代码 分 离 。 

。 模板 代码 包含 在 «script» 元 素 中 。 

。 模板 中 的 HTML 结构 与 普通 网 页 中 的 HTML 结构 相同 。 

。 Mustache 使 用 包含 在 双 括 号 中 的 变量 来 填充 数据 。 

e Mustache 使 用 参照 系 来 遍历 演讲 者 数组 。 从 HTTP 调用 中 返回 的 是 一 个 匿名 集合 ， 攻 
此 我 们 将 所 有 的 元 素 包 含 在 COR) 和 {{/.}} 之 间 来 设 定 参照 系 。 如 果 返 回 的 数组 属于 
某 个 字段 (如 speakers)， 则 参照 系 会 以 {{#speakers}} FK, DA {{/speakers}} 结束 。 

。 模板 中 的 变量 表示 特定 参照 对 象 中 的 字段 名 。 比 如， 遍历 演讲 者 数组 时 ，{{firstName}} 
变量 可 以 获取 当前 成 员 的 FirstName 字段 的 值 。 


如 需 深 入 了 解 Mustache, H% Wern Ancheta 撰写 的 一 篇 很 不 错 的 文章 “Easy Templating 
with Mustache.js" 。 
除了 Mustache, JavaScript 社区 也 经 常 使 用 其 他 一 些 模板 库 。 


Handlebars.js 
Handlebars 和 Mustache 非常 相似 。 



































Underscore.js 


Underscore 是 一 个 通用 工具 库 ， 其 中 包含 一 些 模板 方面 的 功能 。 


另外 ， 大 多 数 MVC 框架 (AngularJS, Ember 和 Backbone) 都 自 带 某 种 形式 的 模板 功能 。 
第 7 章 将 详细 介绍 Mustache 和 Handlebars, 


例 2-15 展示 了 重 构 后 使 用 Mustache 的 app/scripts/main.js 文件 。 











例 2-15 speakers-web-3/app/scripts/main.js 
"Use strict'; 


console.log('Hello JSON at Work! '); 


$(document).ready(function() { 





function addSpeakersMustache(speakers) { 
var tbody = $('#speakers-tbody'); 
$.get('templates/speakers-mustache-template.html', function(templatePartial) { 
var template = $(templatePartial).filter('s&speakerTemplate').html(); 


tbody.append(Mustache.render(template, speakers)); 
}).fail(function() { 
alert("Error loading Speakers mustache template"); 
IDE 
} 


$.getJSON( 'http://localhost:5000/speakers', 


function(data) { 
addSpeakersMustache(data); 


} 
); 
}); 
日 之 前 的 Mustache 模板 将 json-server 所 提 











在 以 上 示例 中 ，addSpeakerMustache() 函数 使 月 

供 的 演讲 者 数据 转换 成 HIML。 我 们 使 用 jQuery 的 $.get() 方法 来 下 载 Mustache 模板 文 
件 。 下 载 完成 后 ， 使 用 之 前 的 方法 找到 主页 上 的 <tbody> 元 素 ， 然 后 使 用 append() 方法 将 
Mustache.rend() 生成 的 HTML 内 容 添加 到 该 元 素 中 。 


最 后 ， 我 们 需要 将 Mustache 添加 到 Web 应 用 程序 中 。 
使 用 Bower 在 Web 应 用 程序 中 安装 Mustache。 可 在 命令 行 中 切换 到 speakers-web-3 目录 ， 








然后 运行 bower install mustache, 
。 在 app/index.html 文件 中 添加 Mustache (紧邻 main.js)， 如 例 2-16 Aras. 
例 2-16 speakers-web-3/app/index.html 
<!doctype html> 


«html lang=""> 


<body> 


«script src-"bower components/mustache.js/mustache.js"»«/script» 


</body> 
</html> 
图 2-5 所 示 的 截图 。 


如 果 之 前 一 直 保 持 应 用 程序 运行 ， 那 么 可 看 到 如 
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© @ / B JSON at Work - MyConference x 








C ñ O localhost:9000 d 
Name About Topics 
Larson Incididunt mollit cupidatat magna JavaScript, AngularJS, Yeoman 
Richard excepteur do tempor ex non eiusmod 


magna exercitation proident nisi non. Sunt 
ad consequat eu non esse excepteur. 
Veniam quis Lorem ea labore ullamco 
veniam nisi do sunt. Nisi irure sit qui irure 
mollit ad aliquip non culpa sint 
reprehenderit ullamco. 


Ester Labore tempor irure adipisicing REST,Ruby on Rails, APIs 

Clements consectetur velit. Ipsum Lorem non mollit 
aliquip. Fugiat est irure quis laboris minim 
anim esse fugiat et culpa exercitation. 
Dolor cillum excepteur officia Lorem 
ullamco magna et cupidatat dolor 
incididunt occaecat adipisicing 
consectetur in. Ullamco ullamco 
commodo nulla eiusmod. Lorem Lorem 
non sunt laboris ut et elit mollit deserunt 
nostrud est et id adipisicing. 


Christensen Proident ex Lorem et Lorem ad. Do Java,Spring,Maven,REST 
Fisher voluptate officia minim in nisi ut sit nisi ex 

eu nostrud do ut. Aute ad dolor tempor 

dolor aute nisi deserunt deserunt ut 

deserunt cillum quis. Ipsum nulla sit 

reprehenderit consequat incididunt 

incididunt dolore et magna aliquip ut ex. 

Cupidatat exercitation ipsum dolore nisi 











2-5. 使 用 Mustache 来 显示 演讲 者 数据 


与 之 前 相 比 ， 由 Mustache 所 显示 的 演讲 者 数据 存在 些许 不 一 致 ， 但 因为 这 种 做 法 通过 调用 
模拟 API 来 获取 数据 ， 同 时 使 用 Mustache 对 HTML 进行 模板 处 理 ， 所 以 Web 应 用 程序 的 
质量 有 了 进一步 的 提升 。 


当然 ， 也 可 以 通过 使 用 AngularJs 或 者 React 来 继续 深入 ， 这 一 点 还 是 留 给 你 自己 来 进行 吧 。 
在 继续 深入 前 ， 请 在 命令 行 窗 口中 使 用 Cul-C 关闭 之 前 所 启动 的 Web 应 用 程序 和 json-server。 


2.6 如何 继续 深入 学 习 JavaScript 


深入 、 全 面 地 了 解 JavaScript 对 于 真正 理解 Node.js 和 JavaScript 框架 (如 Angular, React, 
Ember, Backbone 等 ) 以 及 Yeoman 这 样 的 构建 管理 工具 是 不 可 或 缺 的 。 如 果 对 JavaScript 
对 象 感到 陌生 ， 觉 得 各 种 花 括 号 、 圆 括号 和 分 号 看 起 来 像 是 语法 的 大 杂烩 ， 别 担心 ， 你 并 
非 个 例 。 每 位 JavaScript 开发 者 在 成 长 过 程 中 都 会 磁 到 类 似 的 问题 。 


以 下 是 可 用 于 加 深 并 拓展 相关 技能 的 网 站 。 


JavaScriptIsSexy 网 站 提供 了 非常 不 错 的 免费 教程 来 帮助 开发 者 提升 至 中 级 或 高 级 水 平 ， 主 
要 包括 以 下 3 个 教程 : 



































。 如 何 正 确 地 学 习 JavaScript; 

。 学 习 中 高 级 JavaScript; 

e JavaScript 内 行 必 备 技能 (Apply, Call 和 Bind), 

随 着 对 这 些 资料 的 学 习 ， 达 到 中 高 级 JavaScript 水 平 后 ， 对 象 和 函数 表达 式 这 些 概念 就 会 
变 成 你 的 常识 。 此 时 ， 使 用 本 章 中 所 提 及 的 JavaScript 工具 和 框架 就 会 变 得 更 得 心 应 手 、 
更 有 效率 。 


2.7 AHEM 


本 章 先 描述 了 JavaScript 和 JSON 间 简 单 的 转换 工作 ， 然 后 逐步 开发 了 一 个 可 运行 的 Web 
应 用 程序 ， 同 时 也 编写 了 向 json-server 发 起 RESTful API 调用 的 单元 测试 。 为 简明 起 见 ， 
本 章 仅 介绍 足以 理解 核心 概念 的 几 项 技术 ， 并 用 其 搭建 了 简单 的 应 用 程序 。 至 此 ， 我 们 对 
JavaScript, Node.js 和 Yeoman 只 是 进行 了 粗浅 的 讲解 。 


2.8 ABMS 


使 用 JavaScript 和 JSON 开发 Web 应 用 程序 后 ， 第 3 章 将 介绍 JSON 在 Ruby on Rails 中 的 
使 用 情况 。 
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AIS 


在 Ruby on Rails 中 使 用 JSON 





上 一 章 介 绍 了 如 何在 JavaScript 中 使 用 JSON， 本 章 将 展示 JSON 在 Ruby on Rails 中 的 使 
用 情况 。 

本 章 内 容 如 下 所 示 : 

。 在 Ruby 中 使 用 MultiJson 来 执行 ISON 的 序列 化 / 反 序列 化 操作 ， 

。 使 用 Ruby RFN JSON; 

。 理解 JSON 中 驼峰 式 命名 的 重要 性 ; 

。 在 Minitest 中 使 用 JSON; 

。 使 用 Minitest 和 ja 发 起 RESTful API 调用 ， 并 对 调用 结果 进行 测试 ; 

。 使 用 Rails 5 搭建 简单 的 JSON API。 

在 本 章 的 应 用 示例 中 ， 我 们 将 对 第 1 章 中 部 署 到 json-server 上 的 数据 进行 RESTful API 
调用 。 然 后 创建 一 个 更 加 真实 的 基于 JSON 的 Web API, JF RESTful API 之 前 ， 我 们 先 
来 了 解 一 下 在 Ruby 和 JSON 之 间 进 行 转换 的 基础 知识 。 











3.1 安装 Ruby on Rails 
正式 开始 前 ， 请 参考 A.3 节 中 的 操作 说 明 来 搭建 开发 环境 。 


3.2 ” Ruby 中 与 JSON 有 关 的 gem 包 


Ruby 中 存在 多 个 提供 ISON 序列 化 / 反 序列 化 功能 的 gem 包 ， 举 例如 下 。 


JSON 
Ruby 默认 提供 的 JSON 包 。 
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oj 

经 过 优化 的 JSON 包 ， 很 多 人 认为 oj 是 Ruby 中 最 快 的 JSON 处 理工 具 。 
yajl 

全 称 为 Yet Another JSON Library, Hl] *5—^* JSON XE”, 
除 此 之 外 ， 还 有 很 多 有 关 ISON 的 gem 包 ， 因 此 很 难 选 择 。 在 这 种 情况 下 ，MultiJson 对 
gem 包 的 选择 和 调用 进行 了 封装 ， 自 动 选 择 当 前 应 用 程序 环境 中 最 快 的 JSON 包 ， 从 而 使 
得 开发 者 无 须 学 习 每 个 JSON 包 的 使 用 。 像 这 样 对 gem 包 所 进行 的 封装 操作 可 以 在 应 用 程 
序 和 某 个 具体 的 JSON 实现 之 间 实 现 解 耦 。 如 需 了 解 更 多 有 关 MuLtiJson 如 何 选择 ISON 
实现 的 信息 ， 可 以 参考 其 GitHub 主页 。 如 需 了 解 详细 文档 ， 可 参考 RubyDoc。 
默认 情况 下 ，MultiJson 使 用 标准 的 ISON gem 包 ， 安 装 oj 后 则 可 对 性 能 进行 优化 。 


gem install multi json 
gem install oj 


安装 oj gem Wa, MultiJson 将 默认 使 用 oj， 而 不 是 标准 的 ISON, 


3.3 用 MutLti]Json 进 行 序列 化 / 反 序 列 化 操作 


应 用 程序 需要 有 能 力 将 Ruby 的 数据 类 型 转换 为 JSON (序列 化 )， 也 需要 有 能 力 进行 相反 
的 操作 ( 反 序列 化 )， 从 而 与 其 他 应 用 程序 进行 JSON 数据 的 交换 。 
























































3.3.1 MultiJsonX]£& 

MultiJson 对 象 提 供 以 下 方法 。 

e MultiJson.dump() 将 Ruby 数据 序列 化 为 ISON. 

e MultiJson.load() 将 JSON 反 序 列 化 为 Ruby 数据 。 
值得 注意 的 是 ，MutLtiJson.dump() 会 执行 以 下 操作 。 


。 当 使 用 oj 来 序列 化 speaker 对 象 时 ,使 用 的 是 Ruby 中 传统 的 下 划 线 分 隔 命名 法 (first_ 
name), ， 而 不 是 推荐 的 更 有 利于 跨 平 台 的 驼峰 式 命 名 法 (firstName), 

。 当 使 用 JSON 来 序列 化 speaker 对 象 时 ， 序 列 化 操作 并 不 会 生成 JSON 字符 串 。 这 是 
为 对 于 ISON gem 包 来 说 ， 只 有 某 个 类 实现 了 to_json() 方法 后 ， 才 能 成 功 序列 化 该 类 
的 对 象 实例 。 

。 对 于 JSON 中 的 键 名 ,使 用 的 是 下 划 线 分 隔 命 名 法 (first_name)， 而 不 是 驼峰 式 命名 
ik (firstName), 


根据 MultiJson 的 RubyDoc 文档 ， 以 下 是 MultiJson.dump() 方法 的 语法 : 
#dump(object, options = {}) 


因为 Multijson 只 是 一 个 封装 ， 所 以 options 的 用 法 取决 于 具体 所 采用 的 JSON 实现 (在 
本 节 示 例 中 ， 此 实现 即 为 0j)。 











: pn 
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3.3.2 ”Ruby 中 简单 数据 类 型 的 JSON 序 列 化 / 反 序列 化 操作 
首先 ， 我们 看 一 下 Ruby 中 基础 数据 类 型 的 序列 化 操作 : 





。 字符 串 
。 布尔 值 
。 数组 
dM 
。 对 象 


例 3-1 展示 了 如 何 使 用 MultiJson 和 oj 来 对 简单 的 Ruby 数据 类 型 进行 序列 化 / 反 序 列 化 
操作 。 


例 3-1 ruby/basic_data_types_serialize.rb 
require 'multi json' 


puts "Current JSON Engine = #{MultiJson.current_adapter()}" 
puts 


age = 39 # 整数 型 
puts "age = #{MultiJson.dump(age) }" 
puts 


full name = 'Larson Richard' # 字符 串 
puts "full name = £(MultiJson.dump(full name)]" 
puts 


registered = true # 布尔 值 
puts "registered = #{MultiJson.dump(reqistered)}" 
puts 





tags = %w(JavaScript, AngularJS, Yeoman) # 字符 串 数 组 
puts "tags = £(MultiJson.dump(tags)]" 
puts 


email = ( email: 'larsonrichardQecratic.com' ) # 哈 希 
puts "email = #{MultiJson.dump(email)}" 
puts 


class Speaker 
def initialize(first name, last name, email, about, 
company, tags, registered) 
(first name = first name 
(last name = last name 
(email = email 
@about = about 
@company = company 
@tags = tags 





@registered = registered 
end 
end 


speaker = Speaker.new('Larson', 'Richard', 'larsonrichardQecratic.com', 
'Incididunt mollit cupidatat magna excepteur do tempor ex non ...', 
'Ecratic', %w(JavaScript, AngularJS, Yeoman), true) 


puts "speaker (using oj gem) = #{MuLtiJson.dump(speaker)}" 
puts 





在 命令 行 中 运行 ruby basic data types serialize.rb 可 以 得 到 以 下 结果 : 


json-at-work => ruby basic data types serialize.rb 
Current JSON Engine = MultiJson: :Adapters: :0j 





age = 39 

full name = "Larson Richard" 

registered - true 

tags = ["JavaScript, " , "AngularJS," , "Yeoman" ] 


email = (["email":"larsonrichardeecratic. com") 


speaker (using oj gem) = ("first name":"Larson" , "last. name" : "Richard", "email":"larsonrichardéecratic. com" , "about" : "Incididunt 
mollit cupidatat magna excepteur do tempor ex non ...","company":"Ecratic" , "tags" : ["JavaScript, " , "AngularJS, " , "Yeoman"] , "reg 
istered":true] 





对 于 标量 类 型 (整数 型 、 字 符 串 、 布 尔 值 ) 来 说 ，MultiJson.dump() 并 没有 提供 什么 有 意 
思 的 功能 。 但 对 于 speaker 对 象 来 说 ，MutLtiJson.dump() 可 以 生成 一 段 驳 杂 但 合法 的 JSON 
字符 串 ， 因 此 显得 比较 有 用 。 正 如 稍 后 将 提 到 的 ，MutLtiJson.dump() 还 可 以 接受 其 他 参数 ， 
从 而 使 得 序列 化 操作 更 加 强大 。 


为 了 增加 结果 的 可 读 性 ， 我 们 将 使 用 :pretty => true 选项 来 优化 speaker 对 象 的 ISON Mi 
出 结果 ， 如 例 3-2 所 示 。 虽 然 对 输出 结果 进行 优化 显示 可 以 增加 可 读 性 ， 但 这 会 降低 效率 ， 
因此 这 一 选项 只 应 在 调试 时 加 以 使 用 。 


例 3-2 ruby/obj_serialize_pretty.rb 
























































require 'multi json' 


speaker = Speaker.new('Larson', 'Richard', 'larsonrichardQecratic.com', 
'Incididunt mollit cupidatat magna excepteur do tempor ex non ...', 
'Ecratic', %w(JavaScript, AngularJS, Yeoman), true) 


puts "speaker (using oj gem) = £(MultiJson.dump(speaker, pretty: true)}" 
puts 


运行 以 上 代码 可 以 得 到 以 下 优化 显示 的 结果 : 
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json-at-work => ruby obj serialize pretty.rb 
Current JSON Engine = MultiJson: : Adapters: :0j 


speaker (using oj gem) = { 
"first name":"Larson", 
"last. name" : "Richard", 
“email":"Larsonrichard@ecratic.com", 
"about":"Incididunt mollit cupidatat magna excepteur do tempor ex non ..." 
"company" : "Ecratic", 
"tags" :[ 
"JavaScript," , 
"AngularJS,", 
"Yeoman" 


> 
"registered": true 





3.3.3 ”用 Multijson 进 行 JSON 反 序列 化 操作 


除了 对 数据 进行 序列 化 ，MultiJson 还 可 以 对 JSON 进行 反 序 列 化 操作 。 本 节 将 使 用 
MultiJson.load() 方法 将 JSON 反 序列 化 为 Ruby Hash。 因 为 speaker 对 象 的 initialize() 
方法 接受 的 参数 类 型 为 字符 串 (与 speaker 对 象 的 属性 类 型 保持 一 致 ) ， 所 以 我 们 需要 对 反 
序列 化 后 的 Hash 进行 转换 ， 将 其 转换 为 用 于 初始 化 speaker 对 象 所 需 的 一 系列 属性 。 好 在 
知名 类 库 OpenStruct 可 以 使 得 Hash 表现 出 对 象 的 行为 ， 因 此 我 们 无 须 编写 任何 代码 即 可 
完成 这 一 转换 工作 。 

例 3-3 展示 了 OpenStruct 的 使 用 。 


例 3-3 ruby/ostruct_example.rb 
require 'ostruct' 























h = ( first name: 'Fred' } 

m = OpenStruct.new(h) 

puts m # 打印 结果 : #<OpenStruct first name-"Fred"» 

puts m.first name # 打印 结果 : Fred 
OpenStruct 是 和 Hash 类 似 的 一 种 数据 结构 ， 它 允许 对 属性 及 其 值 进 行 名 称 - 值 对 定义 ， 
也 提供 以 属性 的 形式 访问 键 值 的 功能 。0penStruct 是 Ruby 核心 语法 的 一 部 分 。 如 需 了 解 
更 多 有 关 OpenStruct 的 信息 ， 可 参考 Ruby 的 核心 文档 。 
当 实 例 化 一 个 新 的 speaker 对 象 时 ， 若 能 以 可 读 的 形式 打印 出 这 一 新 对 象 ， 那 么 对 调试 工 
作 是 非常 有 利 的 。 如 果 使 用 普通 的 puts 语句 ， 得 到 的 结果 一 般 如 下 所 示 : 

puts speaker # #<Speaker :0x007f84412e0e38> 
如 果 使 用 awesome print gem 包 ， 则 可 以 得 到 更 具 可 读 性 的 输出 结果 。 如 需 了 解 更 多 相关 
信息 ， 可 参考 awesome_print 的 GitHub 主页 。 
运行 例 3-4 的 代码 前 ， 请 在 命令 行 中 安装 awesome_print 包 。 


gem install awesome print 
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例 3-4 ruby/obj_deserialize.rb 
require 'multi json' 
require 'ostruct' 
require 'awesome print' 


puts "Current JSON Engine = #{MultiJson.current_adapter()}" 
puts 


class Speaker 
def initialize(first name, last name, email, about, 
company, tags, registered) 
Qfirst name = first name 
Qlast name = last name 
(email = email 
@about = about 
@company = company 


@tags = tags 
@registered = registered 
end 


end 


speaker = Speaker.new('Larson', 'Richard', 'larsonrichardQecratic.com', 
'Incididunt mollit cupidatat magna excepteur do tempor ex non ...', 
'Ecratic', %w(JavaScript, AngularJS, Yeoman), true) 


json speaker = MultiJson.dump(speaker, pretty: true) 
puts "speaker (using oj gem) = #{MuLtiJson.dump(speaker)}" 
puts 


ostruct spkr = OpenStruct.new(MultiJson.load(json speaker)) 


speaker2 = Speaker.new(ostruct spkr.first name, ostruct spkr.last name, 
ostruct spkr.email, ostruct spkr.about, ostruct spkr.company, 
ostruct spkr.tags, ostruct spkr.registered) 


puts "speaker 2 after MultiJson.load()" 
ap speaker2 
puts 


运行 这 一 示例 后 可 以 看 到 ， 代 码 成 功 地 将 保存 在 json. speaker 变量 中 的 JSON 字符 串 反 
序列 化 为 Openstruct 对 象 ， 然 后 再 将 该 0penSstruct 对 象 转换 为 新 的 speaker 实例 ， 即 
speaker2。 注 意 该 示例 对 awesome_print 中 的 ap 方法 的 使 用 ， 代 码 使 用 了 ap 而 不 是 内 置 的 
puts， 从 而 优化 显示 了 对 象 的 输出 结果 。 


json-at-work => ruby obj deserialize.rb 
Current JSON Engine = MultiJson::Adapters: :0j 






































speaker (using oj gem) = ("first name":"Larson" , "Last. name" : "Richard", "email":"larsonrichardéecratic. com" , "about" : "Incididunt 
mollit cupidatat magna excepteur do tempor ex non ...","company":"Ecratic", "tags" : ["JavaScript, " , "AngularJS, " , "Yeoman"], " reg 
istered":true] 


speaker 2 after MultiJson.load() 

#<Speaker :@x007fc77482a260 first name-"Larson", last name-"Richard", @email="Larsonrichard@ecratic.com", @about="Incididunt 
mollit cupidatat magna excepteur do tempor ex non ...", @company="Ecratic", @tags=["JavaScript,", "AngularJS,", "Yeoman"], e 
registered=true> 
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RUE. multi json 和 oj 可 以 高 效 地 处 理 JSON ， 但 有 时 开发 者 需要 对 数据 的 序列 化 过 程 有 更 
多 的 把 控 。 


3.3.4 ”关于 JSON 和 驼峰 式 命名 


不 管 你 是 否 已 经 注意 到 ，JSON 中 的 键 名 / 属性 名 通常 都 是 以 驼峰 式 命名 形式 存在 的 。 比 
如 ， 表 示 某 人 名 字 的 键 名 一 般 会 命名 为 firstName。 但 到 目前 为 止 ， 我 们 所 了 解 的 Ruby 中 
的 ISON 类 库 都 是 将 键 名 以 下 划 线 分 隔 的 形式 表示 的 (first_name)。 这 种 做 法 在 自 娱 自 乐 
的 小 型 代码 示例 和 单元 测试 中 可 能 没有 问题 ， 但 并 不 兼容 主流 做 法 。 以 下 是 具体 原因 。 


。 JSON 必须 具备 互 操 作 性 。 虽 然 以 下 观点 可 能 会 冒犯 很 多 热爱 Ruby 的 人 人， 也 可 能 会 被 
批评 为 无 意义 的 繁 文 末节 ， 但 我 还 是 不 得 不 说 : JSON 和 REST 的 全 部 意义 就 在 于 在 多 
种 多 样 的 应 用 程序 系统 之 间 实 现 互 操作 性 。 除 了 Ruby， 还 存在 其 他 编程 语言 ， 而 这 些 

编程 语言 都 是 采用 驼峰 式 命名 法 (FirstName) 的 。 如 果 一 个 API 以 一 种 意 想不到 的 方 
式 工 作 ， 那 么 是 不 会 有 人 愿意 使 用 这 样 的 API 的 。 

。 在 JSON 中 存在 使 用 驼峰 式 命名 法 的 重量 级 参与 者 。 

— Google 的 JSON 编码 规范 对 驼峰 式 命名 法 进行 了 标准 化 。 
- 基于 JSON 的 大 多 数 开 放 API 都 使 用 了 驼峰 式 命名 法 ， 如 亚马逊 的 AWS, Facebook 
以 及 LinkedIn。 

。 应 该 避免 单个 平台 影响 整体 系统 。 不 论 生 成 或 读 取 ISON 的 平台 /语言 是 什么 ，JSON 
的 呈现 都 应 该 保持 不 变 。Ruby on Rails 社区 偏好 使 用 以 下 划 线 分 隔 来 命名 的 做 法 ， 这 在 
Ruby 平台 内 部 没有 任何 问题 ， 但 这 一 编程 语言 的 内 部 习惯 不 应 该 影响 整体 API, 


3.8.5 用 ActiveSupport 进 行 JSON 序 列 化 操作 


ActiveSupport 这 一 gem 包 提 供 了 从 Rails 中 抽取 出 来 的 一 些 功能 ， 包 括 时 区 、 国 际 化 以 及 
JSON 编码 / 解码 等 。ActiveSupport 中 的 JSON 模块 提供 了 以 下 功能 : 


。 在 驼峰 式 命名 和 下 划 线 分 隔 命 名 之 间 进 行 转换 ， 
。 选择 目标 对 象 的 部 分 内 容 进行 序列 化 。 
可 以 在 命令 行 中 运行 以 下 命令 来 安装 ActiveSupport: 


gem install activesupport 













































































我 们 使 用 ActiveSupport: : JSON.encode() 将 speaker 对 象 序列 化 为 JSON， 如 例 3-5 所 示 。 


fij 3-5 ruby/obj serialize active support.rb 
require 'active support/json' 
require 'active support/core ext/string' 


speaker = Speaker.new('Larson', 'Richard', 'larsonrichardQecratic.com', 
'Incididunt mollit cupidatat magna excepteur do tempor ex non ...', 
'Ecratic', *w(JavaScript, AngularJS, Yeoman), true) 


json = ActiveSupport::JSON.encode(speaker).camelize(first letter = :lower) 





52 | $3 


puts "Speaker as camel-cased JSON \n#{json}" 
puts 


json = ActiveSupport: :JSON.encode(speaker , 
only: ['first name', 'last name']) 
.camelize(first letter - :lower) 


puts "Speaker as camel-cased JSON with only firstName and lastName \n#{json}" 
puts 


可 以 看 到 ActiveSupport: : J50N. encode() 在 以 上 示例 中 提供 了 以 下 选项 。 


。 通过 链 式 调用 camelize() 将 键 名 转换 成 驼峰 式 命 名 (firstName)。 值 得 注意 的 是 ， 键 名 
中 的 首 字母 默认 为 大 写 , 因 此 需要 使 用 first letter = :Lower 参数 将 其 转换 为 小 写 (小 
驼峰 命名 法 )。 

。 使 用 only: 参数 选择 speaker 对 象 的 一 部 分 进行 序列 化 。 


运行 以 上 代码 后 可 以 看 到 以 下 结果 : 


json-at-work => ruby obj_serialize_active_support.rb 

Speaker as camel-cased JSON 

("firstName" : "Larson" , "LastName" : "Richard" , "email":"Larsonrichard@ecratic.com","about":"Incididunt mollit cupidatat magna exc| 
epteur do tempor ex non ...","company" : "Ecratic" , "tags" : ["JavaScript, " , "AngularJS, " , "Yeoman"] , "registered" :true] 



























































Speaker as camel-cased JSON with only firstName and lastName 
("firstName" : "Larson" , "LastName" : "Ri chard") 





如 果 只 是 需要 将 键 名 从 下 划 线 分 隔 转换 为 驼峰 式 命 名 ， 那 么 还 可 以 选择 awrence 包 这 一 简 
单 的 替代 方案 。 使 用 awrence 将 Hash 键 中 的 下 划 线 分 隔 命 名 转换 为 驼峰 式 命名 后 ， 即 可 将 
其 转换 为 驼峰 式 命名 格式 的 JSON。 对 于 awrence 包 的 具体 使 用 ， 我 的 经 验 不 多 ， 因 此 这 
一 点 还 是 留 给 你 自己 来 实践 吧 。 


3.3.6 用 ActiveSupport 进 行 JSON 反 序列 化 操作 


ActiveSupport 还 可 以 对 ISON 进行 反 序列 化 操作 。 本 市 会 使 用 decode() 方法 将 ISON 反 序 
列 化 为 Hash。 和 之 前 一 样 ， 我 们 使 用 Openstruct 和 awesome print 来 辅助 创建 对 象 实例 ， 
并 优化 显示 结果 ， 如 例 3-6 所 示 。 


例 3-6  ruby/obj deserialize active support.rb 
require 'multi json' 
require 'active support/json' 
require 'active support/core ext/string' 
require 'ostruct' 
require 'awesome print' 























speaker = Speaker.new('Larson', 'Richard', 'larsonrichardQecratic.com', 
'Incididunt mollit cupidatat magna excepteur do tempor ex non ...', 
'Ecratic', %w(JavaScript, AngularJS, Yeoman), true) 


json speaker = ActiveSupport::JSON.encode( speaker) 
puts "speaker (using oj gem) = #{ActiveSupport: : JSON.encode(speaker ) }" 
puts ostruct spkr = OpenStruct.new(ActiveSupport: :JSON.decode(json_speaker ) ) 
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plissken 这 一 gem 包 可 以 将 Hash 键 名 中 的 驼峰 式 命名 转换 为 下 划 线 分 隔 命 名 。 接 下 来 的 


在 命令 行 中 运行 以 上 代码 后 可 得 到 以 下 结果 : 


speaker2 = Speaker.new(ostruct_spkr.first_name, ostruct spkr.last name, 


ostruct spkr.email, ostruct spkr.about, ostruct spkr.company, 


ostruct spkr.tags, ostruct spkr.registered) 


puts "speaker 2 after ActiveSupport::JSON.decode()" 
ap speaker2 
puts 




















json-at-work => ruby obj deserialize active. support.rb 

speaker (using oj gem) = í"first name":"Larson", "last " "Richard" , "email":"larsonrichardeecratic. com" , " ":"Incididunt 
mollit cupidatat magna excepteur do tempor ex non ...","company":"Ecratic" , "tags" : ["JavaScript, " , "AngularJS, " , "Yeoman"] , "reg 
istered" :true} 


speaker 2 after ActiveSupport: : JSON.decodeQ) 

#<Speaker :@x007fe73cOa4eb8 @first_name="Larson", @last_name="Richard", @email="Larsonrichard@ecratic.com", @about="Incididunt 
mollit cupidatat magna excepteur do tempor ex non ...", @company="Ecratic", @tags=["JavaScript,", "AngularJS,", "Yeoman"], e 
registered=true> 








元 测试 中 将 使 用 plissken, 


3 


.4 用 模拟 API 进 行 单元 测试 





ü 





了 解 了 如 何 对 speaker 对 象 进行 序列 化 / 反 序列 化 操作 后 ， 我 们 可 以 运行 一 个 简单 的 服务 
器 端 单元 测试 程序 ， 以 对 json-server 提供 的 模拟 API 进行 测试 。 


3.4.1 使 用 Minitest 即 可 完成 单元 测试 


Minitest (Ruby 核心 的 一 部 分 ) 和 RSpec 是 最 常用 的 两 个 Ruby 测试 框架 。 两 者 都 非常 优 


秀 





， 但 为 了 重点 关注 JSON， 我 们 只 讨论 其 中 一 个 框架 的 使 用 。 


一 方面 ，Minitest: 


是 Ruby 标准 库 的 一 部 分 ， 因 此 无 须 额 外 的 安装 工作 ， 
属于 轻 量 级 类 库 ， 且 简单 易 用 ， 
提供 了 RSpec 所 具备 的 大 多 数 功能 。 






































另 一 方面 ，RSpec: 
需要 额外 安装 rspec 这 一 gem 包 ,不 过 该 gem Æ Ruby on Rails 社区 中 有 着 广泛 的 使 用 ， 


两 者 间 的 选择 更 多 取决 于 个 人 偏好 ， 因 为 无 论 哪个 测试 





庞大 、 复杂 , 其 代码 库 比 Minitest 大 8 pe, 
匹配 规则 比 Minitest 更 丰富 。 











于 Minitest 是 Ruby 标准 库 的 一 部 分 ， 因 此 本 书 选择 使 用 Minitest。 
Minitest 允许 使 用 BDD 风格 (Minitest::Spec) 和 TDD 风格 (Minitest::Test) 来 编写 测 


试 。 

















出 于 以 下 原因 ， 我 们 使 用 Minitest: Spec, 


我 个 人 偏好 使 用 BDD， 即 用 简单 的 英文 语句 来 描述 每 个 测试 用 例 。 
这 一 做 法 与 RSpec 类 似 ， 因 此 会 让 使 用 RSpec 的 开发 者 感到 熟悉 。 


























E 架 都 是 可 以 正常 完成 工作 的 。 由 
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。 与 本 书 其 他 章节 中 基于 JavaScript 的 Mocha/Chai 测试 代码 保持 一 致 。 


本 章 只 介绍 了 Minitest 的 一 些 基础 知识 。 如 需 了 解 更 多 信息 ， 可 参考 Chris Kottom 所 著 的 
The Minitest Cookbook, 


3.4.2 ”设置 单元 测试 环境 


正式 开始 前 ， 需 要 先 完 成 测试 环境 的 设置 工作 。 如 尚未 安装 Ruby on Rails, "BA A.3 节 
和 A.3.3 节 中 的 内 容 。 如 需 依照 本 节 的 描述 运行 代码 示例 中 的 Ruby 项 目 ， 可 使 用 cd 命令 
切换 到 chapter-3/speakers-test 目录， 并 执行 以 下 命令 来 安装 项 目 依赖 : 


bundle install 
对 于 Ruby SHAMS, Bundler 可 以 帮助 进行 依赖 管理 。 
如 需 手 动 创建 本 节 中 的 Ruby 项 目 ， 可 参考 本 书 在 GitHub 上 的 相关 指导 步骤 。 


3.4.3 ”测试 数据 

本 节 将 使 用 之 前 章节 中 所 提供 的 演讲 者 数据 作为 测试 数据 ， 并 将 其 部 署 为 RESTful API, 
与 之 前 的 做 法 相同 ， 我 们 将 使 用 json-server 这 一 Node.js 模块 把 data/speakers.json 文件 部 
署 为 Web API。 如 需 了 解 有 关 安 装 json-server 的 信息 ， 请 参考 A.2.5 节 中 的 内 容 。 


以 下 是 在 本 地 机 器 中 使 用 5000 端口 运行 json-server 的 步骤 


cd chapter-3/data 









































json-server -p 5000 ./speakers.json 


访问 该 API 时， 还 可 以 通过 在 URI (如 http://localhost:5000/speakers/1) 中 添加 id 来 获取 
单个 演讲 者 的 数据 。 准 备 好 模拟 API 后 ， 就 可 以 开始 编写 单元 测试 了 。 


3.4.4 用 Minitest 测 试 API 所 提供 的 JSON 

本 节 的 单元 测试 实现 了 以 下 功能 : 

模拟 的 演讲 者 数据 API 发 起 HTTP 调用 ， 

查 HTTP 响应 体 中 的 值 ， 并 将 其 与 预期 结果 进行 对 比 。 

与 之 前 的 章节 一 样 ， 本 节 会 继续 使 用 Unirest 这 一 API 封装 工具 ， 但 在 选择 具体 类 库 时 会 
使 用 Unirest 的 Ruby 实现 。 需 要 注意 的 是 ，Unirest 包 会 接受 HTTP 响应 体 中 的 JSON, 将 
其 解析 为 Ruby 中 的 Hash， 然 后 再 将 该 Hash 以 HTTP 响应 体 的 形式 返回 给 调用 方 。 这 种 做 
法 意味 着 单元 测试 用 例 所 测试 的 并 不 是 原始 的 JSON 数据 ， 而 是 从 API 所 提供 的 JSON 响 
应 中 转换 得 到 的 Hash。 


3.4.5 ”对 演讲 者 数据 的 单元 测试 
例 3-7 中 的 单元 测试 展示 了 如 何 使 用 Unirest 向 json-server 所 提供 的 模拟 API 发 起 调用 ， 
并 测试 响应 。 
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fij 3-7  speakers-test/test/speakers spec.rb 


require 'minitest helper' 


require 'unirest' 
require 'awesome print' 
require 'ostruct' 
require 'plissken' 
require 'jq/extend' 


require relative '../models/speaker' 
describe 'Speakers API' do 
SPEAKERS, ALL URI = 'http://localhost:5000/speakers' 


before do 
(res = Unirest.get SPEAKERS ALL URI, 
headers:{ 'Accept' => "application/json" } 


end 


it 'should return a 200 response' do 

expect(@res.code).must_equal 200 

expect(@res.headers[:content_type]).must_equal 'application/json; charset=utf-8' 
end 


it 'should return all speakers' do 
speakers = @res.body 
expect (speakers) .wont_be_nil 
expect (speakers) .wont_be_empty 
expect(speakers. length) .must_equal 3 
end 


it 'should validate the 3rd speaker as an Object' do 
speakers = @res.body 
ostruct_spkr3 = OpenStruct.new(speakers[2].to_snake_keys()) 


expect(ostruct spkr3.company).must equal 'Talkola' 

expect(ostruct spkr3.first name).must equal 'Christensen' 
expect(ostruct spkr3.last name).must equal 'Fisher' 

expect(ostruct spkr3.tags).must equal ['Java', 'Spring', 'Maven', 'REST'] 


speaker3 = Speaker.new(ostruct spkr3.first name, ostruct spkr3.last name, 
ostruct spkr3.email, ostruct spkr3.about, 
ostruct spkr3.company, ostruct spkr3.tags, 
ostruct spkr3.registered) 


expect(speaker3.company).must equal 'Talkola' 

expect(speaker3.first name).must equal 'Christensen' 

expect(speaker3.last name).must equal 'Fisher' 

expect(speaker3.tags).must equal ['Java', 'Spring', 'Maven', 'REST'] 
end 





it 'should validate the 3rd speaker with jq' do 
speakers = @res.body 
speaker3 = speakers[2] 
speaker3.jq('.company') {|value| expect(value).must equal 'Talkola'} 
speaker3.jq('.tags') {|value| 
expect(value).must equal ['Java', 'Spring', 'Maven', 'REST']} 
speaker3.jq('.email') {|value] 
expect(value).must equal 'christensenfisher(talkola.com') 
speaker3.jq('. | "\(.firstName) V(.lastName)"') {|value| 
expect(value).must equal 'Christensen Fisher'} 
end 


end 


对 于 这 一 单元 测试 ， 需 要 注意 以 下 儿 点 。 


minitest helper 将 配置 工作 进行 归 总 ， 并 将 其 从 测试 代码 中 提取 出 来 。 本 章 稍 后 将 详 
细 介 绍 Minitest 中 的 辅助 模块 。 

测试 代码 在 Minitest 的 before 方法 中 同步 地 执行 Unirest 的 GET 请 求 ， 并 获得 响应 ， 从 
而 避免 配置 代码 的 重复 。 在 describe 语句 所 定义 的 范围 内 ，Minitest 会 在 执行 每 个 测试 
FAG] (Bl it 语句 ) 前 运行 一 次 before() 方法 。 

should return all speakers 这 一 测试 用 例 执行 了 以 下 操作 。 


BE 





















































确认 HTTP 响应 体 不 为 空 。 
检查 API 所 返回 的 演讲 者 数目 是 否 为 3。 





should validate the 3rd speaker as an Object 这 一 测试 用 例 执 行 了 以 下 操作 。 


从 HTTP 响应 体 (eres.body) 中 抽取 出 以 Hash 形式 表示 的 演讲 者 数据 。 此 时 ， 

Unirest 已 经 对 由 API 所 提供 的 ISON 进行 了 解析 ， 并 将 其 转换 成 了 Hash, 

使 用 openstruct.new() 将 第 三 个 演讲 者 的 Hash 数据 转换 为 OpenStruct 结构 。 

plissken gem 提供 的 to_snake_keys() 方法 可 以 将 Hash 键 名 中 的 驼峰 式 命 名 

(firstName) 转换 成 以 下 划 线 分 隔 命 名 (first_name)， 从 而 与 Ruby 中 的 编程 习惯 

保持 兼容 。 

使 用 Minitest 中 BDD 风格 的 expect 断言 语句 来 检查 期 望 结果 。 

4 第 三 个 演讲 者 的 company, first name, last name 和 tag 值 需要 与 speakers.json 
文件 中 的 值 保 持 一 致 。 





should validate the 3rd speaker with jq 这 一 测试 用 例 的 工作 机 制 如 下 所 示 。 


使 用 ja 查询 语句 (如 company) 来 检查 测试 中 的 字段 值 。jq 允许 对 基于 ISON 的 
Hash 进行 直接 查询 ， 而 无 须 将 Hash 转换 为 对 象 ， 因 此 能 简化 单元 测试 的 编写 工作 。 
ja 是 一 个 强大 的 ISON 搜索 工具 ， 第 6 章 将 对 其 进行 详细 介绍 。 


























字符 串 拼 接 ， 以 便 得 到 演讲 者 的 全 名 后 再 进行 相关 测试 。 
ruby-jq gem 提供 了 jq 在 Ruby 中 的 实现 。 


























命令 行 中 使 用 bundle exec rake 来 执行 该 测试 ， 可 以 得 到 以 下 结果 : 
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json-at-work => bundle exec rake 
Started with run options --seed 42108 


Speakers API 
test 0001 should return a 200 response 
test 0004 should validate the 3rd speaker with jq 


test 0003 should validate the 3rd speaker as an Object 
test 0002 should return all speakers 


Finished in 0.03299s 
4 tests, 18 assertions, 0 failures, 0 errors, 0 skips 

















PASS (@.@1s) 
PASS (@.@2s) 
PASS (0.00s) 
PASS (0.00s) 


rake 是 Ruby 中 常用 的 构建 工具 。bundle exec rake 命令 执行 了 以 下 具体 操作 。 


。 rake 使 用 了 项 目的 Gemfile 中 所 列举 的 gem 包 。 
。 rake 配置 中 将 test 作为 默认 任务 。 


Rakefile 文件 中 定义 了 具体 的 构建 任务 ， 如 例 3-8 所 示 。 


例 3-8 speakers-test/Rakefile 
require 'rake/testtask' 








Rake::TestTask.new(:test) do |t| 
t.libs = *w(lib test) 
t.pattern - 'test/**/* spec.rb' 
t.warning - false 

end 


task :default -» :test 














默认 情况 下 ，Minitest 不 会 显示 测试 是 否 已 通过 。 而 在 之 前 的 单元 测试 运行 结果 中 ， 我 们 
看 到 输出 结果 中 显示 了 通过 测试 的 用 例 。 这 是 因为 speakers-test 项 目 中 使 用 了 minitest- 








reporters gem 来 提升 输出 结果 的 可 读 性 。 








例 3-9 中 的 Minitest 辅助 模块 对 speakers_spec 中 所 使 用 的 minitest 和 minitest-reporters 


gem 进行 了 配置 。 


例 3-9  speakers-test/test/minitest helper.rb 
require 'minitest/spec' 
require 'minitest/autorun' 


require "minitest/reporters" 


Minitest::Reporters.use! Minitest::Reporters::SpecReporter.new 








考虑 到 完整 性 ， 例 3-10 展示 了 保存 演讲 者 数据 的 Speaker 类 。 


例 3-10  speakers-test/models/speaker.rb 


class Speaker 
attr accessor :first name, :last name, :email, 
:about, :company, :tags, :registered 


def initialize(first name, last name, email, about, 
company, tags, registered) 
(first name = first name 
(last name = last name 
(email = email 





(about = about 

@company = company 

@tags = tags 

@registered = registered 

end 
end 

这 段 代 码 很 普通 也 很 简单 。 
。 为 遵循 Ruby 项 目 中 普遍 接受 的 惯例 ，speaker.rb 文件 保存 在 models 文件 夹 中 。 
e attr_accessor 定义 了 Speaker 类 的 数据 成 员 ( 如 first_name) 及 其 getter/setter 访问 方法 。 
e 当 调 用 Speaker.new() 时 ，initialize() 方法 负责 对 数据 成 员 进 行 初始 化 。 


继续 阅读 前 ， 请 在 命令 行 中 敲 击 Ctrl-C 来 关闭 json-server。 


3.4.06 有关 Ruby 和 Minitest 的 更 多 学 习 资料 
本 章 只 介绍 了 Ruby 和 Minitest 的 基础 知识 。 如 需 继续 深入 学 习 ， 可 参考 以 下 学 习 资 料 : 
e Jeremy McAnally 和 Assaf Arkin 所 著 的 《Ruby 程序 员 修炼 之 道 (GE 20» 55 


* David A. Black 所 著 的 The Well-Grounded Rubyist, 2nd Ed. (Manning 出 版 社 ) ; 
e Chris Kottam 所 著 的 Minitest Cookbook. 


3.4.7 ”似乎 少 了 点 什么 

到 目前 为 止 ， 单 元 测试 成 功 地 对 JSON 数据 进行 了 检测 ， 测 试 过 程 还 算 优雅 ， 但 并 不 完美 。 
原因 在 于 测试 代码 必须 一 一 检查 所 有 的 预期 字段 ， 这 无 疑 是 笨拙 而 索 琐 的 。 对 于 庞大 而 又 
结构 复杂 的 ISON 文档 来 说 ， 可 以 想象 同样 的 做 法 将 会 带 来 何等 艰 苗 的 工作 。 对 于 这 一 问 
题 ， 其 中 一 个 解决 方案 是 使 用 JSON Schema。 第 5 章 将 对 此 进行 详细 介绍 。 

本 市 展示 了 如 何 部 署 和 调用 模拟 API， 接 下 来 我 们 将 用 Ruby on Rails 搭建 一 个 小 型 的 
RESTful API。 


3.5 用 Ruby on Rails 搭 建 小 型 Web API 


了 解 了 如 何 对 speaker 对 象 进行 序列 化 / 反 序 列 化 操作 ， 以 及 如 何 对 json-server 提供 的 模 
拟 API 进行 单元 测试 后 ， 本 节 将 介绍 如 何 使 用 API 数据 来 搭建 简单 的 Web 应 用 程序 ， 并 
将 其 展示 给 用 户 。 
我 们 将 继续 使 用 演讲 者 数据 ， 并 通过 Rails 5 将 其 创建 为 API。 因 为 Rails 5 这 一 版 本 包含 
了 rails-api， 所 以 可 用 于 创建 一 个 仅 包含 API 功能 的 Rails 应 用 程序 。rails-api 一 开始 
是 一 个 独立 的 gem， 之 后 才 被 整合 为 Rails 框架 的 一 部 分 。 

本 节 将 搭建 2 个 基于 Rails 的 API 应 用 程序 ， 以 演示 AMS 中 的 一 些 相关 功能 。 


speakers-api-1 
创建 API， 提 供 驼 峰 式 命名 格式 的 JSON, 

















































































































注 1: 此 书 已 由 人 民 邮 电 出 版 社 出 版 。 一 一 编者 注 
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speakers-api-2 


创建 API， 提 供 定 制 化 的 JSON 文档 。 
正式 开始 前 ， 我 们 先 来 看 一 下 API 中 JSON 生成 工具 的 选择 。 


3.5.1 选择 JSON 序 列 化 工具 
Ruby on Rails 中 存在 多 个 JSON 生成 方案 。 以 下 列举 了 一 些 使 用 最 广泛 的 技术 。 


ActiveModel::Serializers (AMS) 
AMS 为 对 象 提供 序列 化 、 校 验 等 功能 。 它 是 Rails API 的 一 部 分 ， 可 在 其 GitHub 主页 
上 找到 相关 详细 文档 。 

Jbuilder 
Jbuilder 是 一 个 领域 专用 语言 (Domain-Specific Language，DSL) 构建 器 ， 可 以 读 取 模 
板 文件 并 对 最 终 的 输出 进行 相应 的 控制 。 有 关 Jbuilder 的 详细 信息 ， 可 以 参考 其 GitHub 
主页 。 

RABL 
RABL (Ruby API Builder Language, Ruby API 构建 器 语言 ) 可 生成 JSON、XML、 
PList, MessagePack 和 BSON, 3X — gem 也 使 用 了 模板 文件 。 有 关 RABL 的 详细 信息 ， 
可 以 参考 其 GitHub 主页 。 


1. 评估 标准 
以 下 是 选择 ISON 序列 化 方案 时 的 一 些 考 虑 点 。 


。 JSON 的 生成 操作 应 当 与 操作 的 目标 对 象 隔离 ， 因 为 目标 对 象 自 身 不 应 该 获知 其 具体 的 
外 界 表 现形 式 。 这 意味 着 目标 对 象 中 不 应 该 存在 任何 与 JSON 生成 有 关 的 代码 。 根 据 
Bob Martin 大 权 的 说 法 ， 如 果 需 要 修改 一 个 类 ， 那 么 只 应 该 存在 一 个 修改 的 理由 ， 即 单 
一 职责 原则 〈 面 向 对 象 设 计 中 SOLID 原则 中 的 第 一 个 原则 )。 如 需 了 解 细节 信息 ， 可 参 
考 Bob Martin 的 面向 对 象 设 计 原 则 网 站 。 当 将 JSON 格式 化 工作 引入 对 象 内 部 时 ， 因 为 
担负 了 以 下 两 个 职责 ， 所 以 该 对 象 就 存在 第 二 个 修改 理由 了 而 这 无 疑 会 加 重 未 来 代码 
修改 的 难度 ) 。 

— 对 象 原 有 的 功能 。 
— JSON 编码 功能 。 

。 控制 类 和 模型 类 不 应 该 与 JSON 的 生成 操作 混杂 在 一 起 。 如 果 发 生 混杂 ， 同 样 会 违反 单 
一 职责 原则 ， 并 使 得 控制 类 / 模型 类 的 代码 变 得 不 那么 灵活 。 正 确 的 做 法 应 当 是 使 用 外 
部 模板 来 隔离 散乱 、 复 杂 的 格式 化 逻辑 ， 以 使 控制 类 和 模型 类 保持 干净 的 状态 。 

。 应 当 可 以 选择 对 象 的 部 分 属性 进行 序列 化 ， 或 者 在 序列 化 时 忽略 部 分 属性 。 


上 述 考 虑 点 看 起 来 有 些 失 之 过 严 ， 但 这 么 做 的 目的 在 于 确保 互 操 作 性 和 一 致 性 。 不 过 ， 因 为 
没有 银 弹 *， 所 以 出 现 别 的 意见 也 完全 在 意料 之 中 。 当 考虑 别 的 做 法 时 ， 以 下 建议 值得 参考 。 














































































































注 2: 在 欧洲 民间 传说 及 19 世纪 以 来 哥 特 小 说 风潮 的 影响 下 ， 银 色 子 弹 往 往 被 描绘 成 具有 驱 魔 功效 的 武器 ， 
后 比喻 为 具有 极端 有 效 性 的 解决 方法 。 一 一 译 者 注 
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。 明白 自己 做 出 决策 的 原因 。 物 色 可 靠 的 软件 工程 师 和 架构 师 来 作为 自己 的 后 备 力量 。 

。 与 其 他 人 合作 并 打成一片 。 确 认 你 所 采用 的 做 法 与 整个 技术 社区 兼容 ， 而 不 是 仅 适 用 于 
单 门 语言 、 单 个 平台 或 者 单个 部 门 这 样 的 特定 技术 领域 。 

建立 评估 标准 后 ， 我 们 来 看 一 下 相应 的 选项 。 

2. AMS、RABL 还 是 Jbuilder 

基于 之 前 描述 的 考虑 点 ， 并 回顾 所 有 的 选项 后 ， 我 们 发 现 这 一 决策 比较 环 手 ， 因 为 AMS, 

RABL 和 Jbuilder 都 能 够 提供 我 们 所 需要 的 绝 大 多 数 特性 。AMS 将 序列 化 操作 提取 到 一 个 

单独 的 Serializer 对 象 中 ，RABL 和 Jbuilder 则 使 用 了 外 部 模板 。 因 为 RABL 无 法 生成 小 

驼峰 式 命 名 的 JSON， 所 以 被 排除 在 外 ， 这 样 选项 就 只 剩 下 AMS 和 Jbuilder 了 。 


在 AMS 和 Jbuilder 之 间作 出 选择 是 比较 困难 的 。 
。 两 者 提供 的 JSON 质量 差不多 。 
。 当 配 置 Rails 来 使 用 oj 时 ， 两 者 的 性 能 没有 差别 。 
最 终 的 决策 取决 于 偏好 。 
。 使 用 Serializer 对 象 程序 化 地 执行 JSON 序列 化 操作 CAMS) 还 是 使 用 模板 技术 (Jbuilder)。 
。 JSON 序列 化 操作 发 生 在 控制 器 中 (AMS) 还 是 发 生 在 表现 层 中 (Jbuilder)。 
双方 都 拥有 不 少 支持 的 观点 。 
支持 AMS 的 观点 
AMS 中 所 有 的 代码 都 是 Ruby 代码 ， 而 Jouilder 对 模板 技术 的 使 用 要 求 开 发 者 学 习 一 门 
新 的 领域 专用 语言 ， 因 此 AMS 方案 更 佳 。 
支持 Jbuilder 的 观点 
使 用 Jbuilder 会 迫使 开发 者 优先 考虑 ISON 的 呈现 ， 并 推动 ISON 与 底层 数据 库 之 间 的 
AA. 
正如 Rails 社区 中 很 多 人 所 说 的 那样 ， 在 AMS 和 Jbuilder 之 间作 出 选择 是 非常 困难 的 ， 两 
者 间 没 有 明显 的 优 劣 ,不管 怎么 选择 ， 都 可 以 在 AP 中 生成 高 质量 的 ISON 响应 。 我 选择 
AMS， 因 为 它 是 Rails 自 带 的 ， 并 且 使 用 AMS 无 须 再 学 习 一 门 新 的 领域 专用 语言 。 


3.5.2 ”speakers-api-1 一 一 创建 API 以 提供 驼峰 式 命 名 风格 































































































的 JSON 
本 市 将 使 用 Rails 5， 通 过 执行 以 下 步骤 来 创建 并 部 署 speakers-api-1 这 一 API, 
(1) 建立 项 目 。 
(2) 编写 源 代码 。 


。 模型 
。 序列 化 工具 类 
。 控制 器 


(3) 部 署 API。 
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(4) 用 Postman 进行 测试 。 


1. 建立 speakers-api-1 项 目 
speakers-api-1 项 目 已 经 包含 在 本 章 的 代码 示例 中 ， 有 具体 位 于 chapter-3/speakers-api-1 目录 下 ， 
因此 无 须 从 头 开始 创建 该 项 目 。 但 为 了 保持 完整 性 ， 以 下 边栏 描述 了 如 何 创建 该 项 目 。 











用 Rails 创建 speakers-api-1 应 用 程序 
可 使 用 以 下 命令 创建 speakers-api-1 这 一 Rails API 项 目 : 
rails new speakers-api-1 -T --api --skip-active-record --skip-action-mailer 
--skip-action-cable 
在 这 一 示例 中 ， 我 们 不 需要 Rails i8 FH eK 99 31 35 XH (ERB, JS, CSS, Asset 
Pipeline 等 ) ， 也 不 需要 数据 库 。 上 述 命令 所 创建 的 Rails API 应 用 程序 不 包含 以 下 内 容 。 


。 基于 Web Hale CH. --api 选项 移 除 了 以 下 资源 。 
— Asset Pipeline 
一 表现 层 文件 

。 测试 (使 用 -T 选 项 进行 移 除 ) 。 

e ActiveRecord (使 用 --skip-active-record 选项 进行 移 除 ) 。 这 意味 着 应 用 程序 无 须 
数据 库 即 可 运行 。 虽 然 听 起 来 有 些 奇 怪 ， 但 这 么 做 能 减少 应 用 程序 的 外 部 依赖 、 简 
化 项 目 创建 过 程 ， 因 此 符合 我 们 的 目标 。 

。 ActionMailer (使 用 --skip-action-mailer 选项 进行 移 除 ) 。 我 们 创建 的 Web API 不 
需要 发 送 电子 邮件 。 

e ActionCable (使 用 --skip-action-cable 选项 进行 移 除 )。 我 们 创建 的 API 不 使 用 
WebSocket, 


上 述 命令 中 的 Rails 生成 工具 依旧 会 创建 控制 器 ， 本 节 稍 后 将 对 此 进行 介绍 。 
rails new 命令 会 创建 speakers-api-l 目录 。 
为 了 在 项 目 中 安装 并 使 用 AMS， 示 例 代码 的 Gemfile 文件 中 添加 了 以 下 两 行 : 


gem 'active model serializers' 
gem 'oj' 


如 本 章 之 前 所 示 ， 我 们 继续 使 用 oj 来 提升 性 能 ， 但 这 对 于 AMS 来 说 并 不 是 必需 的 。 














完成 项 目的 创建 后 ， 需 要 安装 相关 的 gem 来 启动 项 目 。 安 装 操作 如 下 所 示 : 
Ed beaker eapld 
BUngler exec spring binsťub -at 

在 这 一 命令 中 ，Bundler 会 根据 项 目的 Gemfile 文件 来 安装 指定 的 gem, 


2. 创建 模型 
例 3-11 中 的 Speaker 类 是 一 个 普通 的 PORO， 用 于 表示 演讲 者 数据 ，API 则 会 将 这 些 数据 
以 JSON 的 形式 呈现 出 来 。 
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例 3-11  speakers-api-l/app/models/speaker.rb 
class Speaker < ActiveModelSerializers::Model 
attr accessor :first name, :last name, :email, 
:about, :company, :tags, :registered 


def initialize(first name, last name, email, about, 
company, tags, registered) 
Qfirst name = first name 
(last name = last name 
(email = email 
@about = about 
@company = company 


@tags = tags 
@registered = registered 
end 
end 


除了 为 speaker 对 象 实例 提供 数据 成 员 、 构 造 器 和 getter/setter 访问 方法 外 ， 以 上 代码 
没有 承担 太 多 工作 。 代 码 中 也 没有 包含 JSON 格式 方面 的 任何 信息 。Speaker 类 继承 自 
ActiveModelSerializers::Model, [Alb AMS 可 以 将 其 转换 为 JSON. 


3. 创建 序列 化 工具 类 
AMS 提供 了 独立 于 控制 器 和 模型 的 序列 化 工具 ， 用 于 将 对 象 序列 化 为 JSON。 本 章 的 代码 
示例 中 已 经 包含 了 SpeakerSerializer 类 ， 以 下 边栏 描述 了 该 类 的 创建 过 程 。 


























生成 SpeakerSerializer 
可 以 在 speakers-web-1 目录 下 执行 以 下 命令 来 生成 speaker 模型 所 对 应 的 SpeakerSerializer 
类 : 
bin/rails generate serializer speaker 
这 一 命令 会 生成 一 个 仅 包 含 id 字段 的 序列 化 工具 类 : 


class SpeakerSerializer < ActiveModel::Serializer 
attributes :id 
end 


以 此 为 基础 ， 可 以 添加 用 于 ISON 序列 化 的 字段 。 














例 3-12 展示 了 在 AMS 中 用 于 将 speaker 对 象 输出 为 JSON 的 SpeakerSerializer 类 。 


例 3-12 — speakers-api-l/app/models/speaker. serializer.rb 


class SpeakerSerializer < ActiveModel::Serializer 
attributes :first name, :last name, :email, 
:about, :company, :tags, :registered 
end 


在 这 一 示例 中 ，attributes 列举 了 会 序列 化 为 JSON 的 所 有 字段 。 
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4. 创建 控制 器 
在 Rails 应 用 程序 中 ， 控 制 器 负责 接受 HTTP 请 求 并 返回 HTTP 响应 。 在 本 市 示 例 中 ,演讲 者 
数据 的 ISON ALA HTTP 响应 体 的 形式 返回 。 本 音 的 代码 示例 中 已 经 包含 了 SpeakersController 
类 ， 以 下 边栏 描述 了 该 类 的 创建 过 程 。 

















生成 SpeakersController 
可 以 在 speakers-web-1 目录 下 执行 以 下 命令 来 生成 SpeakersController X: 
bin/rails generate controller speakers index show 


这 一 命令 会 生成 一 个 包含 空白 的 index 和 show 方法 的 控制 类 ， 同 时 在 app/config/routers.rb 
文件 中 添加 相应 的 HTTP 路 由 。 








例 3-13 展示 了 实现 index 和 show 方法 的 完整 SpeakersController 类 。 


fij 3-13 speakers-api-1/app/controllers/speakers_controller.rb 
require 'speaker' 


class SpeakersController « ApplicationController 
before action :set speakers, only: [:index, :show] 


# GET /speakers 
def index 

render json: @speakers 
end 


# GET /speakers/:id 
def show 
id = params[:id].to_i - 1 


if id >= 0 && id < @speakers. length 
render json: @speakers[id] 
else 
render plain: '404 Not found', status: 404 
end 
end 


private 


def set_speakers 
@speakers = [] 


(speakers << Speaker.new('Larson', 'Richard', 'larsonrichard(ecratic.com', 
'Incididunt mollit cupidatat magna ...', 'Ecratic', 
['JavaScript', 'AngularJS', 'Yeoman'], true) 


(speakers << Speaker.new('Ester', 'Clements', 'esterclements@acusage.com', 
'Labore tempor irure adipisicing consectetur ...', 'Acusage', 


['REST', 'Ruby on Rails', 'APIs'], true) 


(speakers «« Speaker.new('Christensen', 'Fisher', 








"christensenfisher@talkola.com', 'Proident ex Lorem et Lorem ad ...', 
'Talkola', 
['Java', 'Spring', 'Maven', 'REST'], true) 

end 


end 





关于 这 段 代 码 ， 以 下 几 点 值得 一 提 。 

speakers 数组 是 硬 编码 的 ， 仅 适用 于 测试 。 真 实 的 应 用 程序 中 会 有 一 个 单独 的 数据 层 来 
负责 从 数据 库 中 读 取 speakers 信息 ， 或 者 通过 外 部 API 调用 来 获取 speakers 数据 。 
index 方法 执行 了 以 下 操作 。 























响应 /speakers URI 上 的 HTTP GET 请 求 。 
读 取 整 个 speakers 数组 ,将 其 转换 成 JSON 数组 的 格式 后 以 HTTP 响应 体 的 形式 输出 。 














ow 方法 执行 了 以 下 操作 。 








rz 


RI /speakers/{id} URI (id 表示 演讲 者 的 ID) 上 的 HTTP GET 请 求 。 

根据 演讲 者 的 ID 读 取 speaker 对 象 数据 ， 将 其 转换 成 JSON 对 象 的 格式 后 以 HTTP 
自 应 体 的 形式 输出 。 

如 果 HTTP 请 求 中 的 id 值 越界 ， 则 控制 器 会 返回 HTTP 404 状态 码 (资源 不 存在 )， 
同时 使 用 render plain 语句 在 HTTP 响应 中 包含 一 段 文本 信息 。 














rz 





当 控 制 器 调用 render 方法 时 ,Rails 会 寻找 匹配 的 序列 化 工具 对 speaker 对 象 进 行 序列 化 ， 
默认 情况 下 使 用 的 工具 即 为 SpeakerSerializer 类 。 

控制 器 和 序列 化 工具 之 间 是 解 耦 的 ， 彼 此 不 会 意识 到 对 方 的 存在 。 执 行 序列 化 操作 的 具体 
代码 存在 于 序列 化 工具 中 ， 不 会 出 现在 控制 器 或 者 模型 中 。 控 制 器 、 模 型 和 序列 化 工具 三 
者 各 司 其 职 。 





























在 Rails 应 用 程序 中 ，Routes 文件 负责 在 URL 和 相应 的 控制 器 方法 间 实 现 映 射 。 前 面 示例 

















中 的 rails generate controller 命令 可 以 用 来 创建 路 由 ， 如 例 3-14 所 示 。 
例 3-14  speakers-api-l/app/config/routes.rb 


Rails.application.routes.draw do 


get 'speakers/index' 
get 'speakers/show' 


# 有 关 本 文件 中 DSL 的 详细 信息 ， 可 查看 : 
# http://guides.rubyonrails.org/routing.html 





end 





可 以 通过 使 用 资源 路 由 来 减少 Routes 文件 的 代码 量 ， 如 例 3-15 所 示 。 
例 3-15  speakers-api-l/app/config/routes.rb 





Rails.application.routes.draw do 


resources :speakers, :only -» [:show, :index] 


# 有 关 本 文件 中 DSL 的 详细 信息 ， 可 查看 : 
# http://guides.rubyonrails.org/routing.html 





end 
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与 单独 定义 index 和 show 方法 的 路 由 不 同 ， 资 源 路 由 这 一 形式 仅 使 用 一 行 代 码 就 完成 了 对 
路 由 的 定义 。 

5. 让 AMS 的 JSON 输 出 采用 驼峰 式 命 名 格式 

默认 情况 下 ，AMS 输出 的 JSON 键 名 会 采用 下 划 线 分 隔 的 格式 (first name 和 Last_ 
name)。 从 应 用 程序 外 部 来 看 ， 当 向 http://localhost:3000/speakers/1 发 送 HTTP GET 请 求 时 ， 
得 到 的 JSON 序列 化 结果 为 : 





























{ 
"first name": "Larson", 
"last name": "Richard", 
"email": "Larsonrichard@ecratic.com", 
"about": "Incididunt mollit cupidatat magna ...", 
"company": "Ecratic", 
"tags": [ 
"JavaScript", 
"AngularJs", 
"Yeoman" 
]， 
"registered": true 
} 























为 了 使 得 ISON 的 输出 结果 与 非 Ruby 客户 端 兼容 ， 可 以 添加 全 局 初始 化 文件 将 输出 格式 
转 为 驼峰 式 命 名 ， 如 例 3-16 所 示 。 


fj 3-16  speakers-api-l/config/initializers/active model serializers.rb 
ActiveModelSerializers.config.key transform - :camel lower 


6. 部 署 API 
在 speakers-api-l 目录 中 运行 rails s 命令 ,将 API 部 署 到 http://localhost:3000/speakers 这 
一 URL 上， 可 以 在 命令 行 窗口 中 看 到 以 下 结果 : 


json-at-work => rails s 

=> Booting Puma 

=> Rails 5.0.2 application starting in development on http://localhost:3000 
=> Run ‘rails server -h` for more startup options 

Puma starting in single mode... 














* Version 3.8.2 (ruby 2.4.0-p0), codename: Sassy Salamander 
* Min threads: 5, max threads: 5 

* Environment: development 

* Listening on tcp://LocaLhost : 3000 

Use Ctrl-C to stop 





7. 用 Postman 测 试 API 

与 第 1 章 中 的 做 法 相同 ， 成 功 运 行 演讲 者 数据 API 后 ， 我 们 将 使 用 Postman 来 测试 第 一 个 
演讲 者 的 数据 。 在 Postman 的 GUI 中 执行 以 下 操作 。 

e 输入 URL: http://localhost:3000/speakers/1。 

。 在 HTTP 方法 中 选择 6ET。 

。 点 击 Send 按钮 。 


点 击 按钮 后 ， 可 以 看 到 Postman 中 的 GET 请 求 成 功 运行 ， 并 获取 到 了 HTTP 200 (OK) 的 状 
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态 码 ， 同 时 HTTP 响应 体 文本 框 中 显示 了 演讲 者 的 ISON 数据 ， 如 图 3-1 所 示 。 











GET http://localhost:3000/speakers/1 Params Save 
Authorization 
Type No Auth 
Body (9) Status: 200 OK — Time: 26 ms 
Pretty SON 
1- f 
2 "firstName": "Larson", 
3 "lastName": "Richard", 
4 "email": "larsonrichardeecratic.com", 
"about": "Incididunt mollit cupidatat magna ...", 
6 "company": "Ecratic", 
7- "tags": [ 
8 "JavaScript", 
9 "AngularJs", 
10 "Yeoman" 
11 s 
12 "registered": true 
13 











3-1: 在 Postman 中 获取 演讲 者 JSON 数据 
BLA CEA T iit Ctrl-C 来 关闭 speakers-api-1 应 用 程序 。 


3.5.3 speakers-api-2 一 一 创建 API 以 提供 自 定 义 风格 的 
JSON 


除了 将 ISON 键 名 转 为 驼峰 式 命 名 格式 ，AMS 还 提供 了 其 他 的 ISON 定制 功能 。speakers- 
api-2 这 一 应 用 程序 将 展示 如 何在 AMS 中 定制 每 个 speaker 对 象 的 ISON 呈现 。 除 了 新 的 
SpeakerSerializer 2É, speakers-api-2 项 目 中 的 所 有 代码 都 与 之 前 的 speakers-api-1 项 目 相 
同 ， 因 此 本 市 仅 描 述 序 列 化 过 程 。 

正式 开始 前 ， 先 安装 gem 来 运行 speakers-api-2 项 目 ， 如 下 所 示 : 


cd speakers-api-2 














bundle exec spring binstub --all 


1. 用 AMS 修 改 JSON 呈 现 
在 不 修改 speaker 对 象 的 情况 下 ， 新 的 SpeakerSerializer 类 合并 first name 字段 和 1Last_ 
name 字段 ， 从 而 在 JSON 中 产生 一 个 新 的 name 字段 ， 如 例 3-17 所 示 。 


例 3-17 speakers-api-2/app/serializers/speaker_serializer.rb 
class SpeakerSerializer < ActiveModel::Serializer 
attributes :name, :email, :about, 
:company, :tags, :registered 








def name 
"it(object.first name) #{object.last_name}" 
end 
end 
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对 于 这 一 示例 有 以 下 两 点 需要 注意 。 
e attributes 4E V. f name 字段 ， 去 除了 first name 和 last name, 
。 在 nane 方法 中 : 
— object 变量 表示 正在 进行 JSON 序列 化 的 speaker 对 象 ; 
— 使 用 了 字符 串 拼接 操作 将 first name 和 last. nane 字段 合并 为 nane 字段 ， 原 始 的 
Speaker 模型 并 不 会 意识 到 该 name 属性 的 存在 。 
通过 attributes 对 JSON 呈现 进行 自 定义 操作 是 非常 强大 的 ， 因 为 它 成 功 地 在 模型 和 
JSON 输出 之 间 进 行 了 解 耦 。 
2. 部 署 API 
在 speakers-api-2 目录 中 运行 rails s 命令 ,将 API 部 署 到 http://localhost:3000/speakers 这 
一 URL 上 。 
3. 用 Postman 测 试 API 
在 Postman 的 GUI 中 向 http://localhost:3000/speakers/1 发 起 HTTP GET 请 求 ， 得 到 的 结果 如 
3-2 所 示 。 



































GET http://localhost:3000/speakers/1 Params LC Save 
Authorization 
Type No Auth 
Body (9) Status: 200 OK — Time: 144 ms 
Pretty JSON 
t= it 
2 "name": "Larson Richard", 
3 "email": “Larsonrichard@ecratic.com" 
4 "about": "Incididunt mollit cupidatat magna ...", 
5 "company": "Ecratic", 
6- ‘tags’ L 
7 "JavaScript", 
8 "AngularJS", 
9 "Yeoman" 
10 i 
11 "registered": true 
12 } 











3-2; 在 Postman 中 获取 自 定 义 的 演讲 者 JSON 数据 





AKERRA, TEAS Fe Ed: Ctrl-C 来 关闭 speakers-api-2 应 用 程序 。 


3.5.4 有 关 Rails 和 Rails API 的 更 多 学 习 资 料 
本 章 只 介绍 了 建立 简单 的 API 应 用 程序 所 需要 的 Rails 操作 和 AMS 知识 。 如 需 继续 这 入 学 
习 ， 可 参考 以 下 学 习 资 料 : 


e Michael Hartl 所 著 的 《Ruby on Rails 教程 》”; 
* Daniel Kehoe 所 著 的 Learn Ruby on Rails 5; 




















iE 3: 此 书 第 4 版 已 由 人 民 邮 电 出 版 社 出 版 。 一 一 编者 注 
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* Abraham Kuri 所 著 的 APIs on Rails: Building REST APIs with Rails ; 
* Chris Kottam 撰写 的 文章 “Get Up and Running with Rails API” ; 
e Kendra Uzia 撰写 的 文章 “Active Model Serializers, Rails, and JSON! OH MY'!", 


3.6 ”本 章 回顾 


本 章 先 描述 了 Ruby 和 JSON 间 的 简单 转换 工作 ， 讨 论 了 JSON 中 驼峰 式 命名 格式 的 重要 
性 ， 然 后 演示 了 如 何 对 一 个 基于 ISON 的 模拟 Web API 进行 调用 (并 使 用 Minitest 来 测试 
调用 结果 )。 最 后 使 用 Rails 5 创建 了 一 个 RESTful API， 并 用 Postman 对 其 进行 了 测试 。 


3.7 ABMS 


学 习 了 如 何 使 用 Ruby on Rails 开发 基于 ISON 的 应 用 程序 后 ， 第 4 章 将 介绍 JSON 在 Java 
和 Spring Boot 中 的 使 用 情况 。 
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在 Java 中 使 用 JSON 





前 面 的 章节 已 经 介绍 了 JSON 在 JavaScript fll Ruby on Rails 中 的 使 用 ， 本 章 将 展示 ISON 
在 Java (第 三 个 也 是 最 后 一 个 平台 ) 中 的 使 用 情况 。 本 章 内 容 包 括 : 

。 在 Java 中 用 Jackson 执行 JSON 的 序列 化 / 反 序列 化 操作 ，; 

。 使 用 Java 对 象 和 JSON; 

。 在 JUnit 中 使 用 JSON; 

。 发 起 RESTful API 调用 ， 并 用 JUnit 和 JsonUnit 测试 调用 结果 ， 

。 用 Spring Boot 搭建 简单 的 JSON API. 


在 本 章 的 应 用 示例 中 ， 我 们 将 对 第 1 章 中 部 署 到 json-server 上 的 数据 进行 RESTful API 
调用 。 然 后 创建 一 个 更 真实 的 基于 ISON 的 Web API, FFA RESTful API 前 ， 我 们 先 来 了 
解 一 下 Java 中 JSON 序列 化 / 反 序 列 化 方面 的 基础 知识 。 


4.1 安装 Java 和 Gradle 

本 章 使 用 Gradle 对 源 代 码 进行 构建 和 测试 。 如 尚未 安装 Java 和 Gradle， 请 参考 A.5 “FN 
A.5.2 节 中 的 内 容 来 搭建 开发 环境 ， 之 后 即 可 运行 本 章 中 的 示例 。 

4.2 Gradle 概 览 


Gradle 继承 了 Apache Ant 和 Maven 等 早期 Java 构建 系统 的 理念 ， 并 得 到 了 广泛 的 应 用 。 
Gradle 可 以 为 Java 项 目 提 供 以 下 功能 。 

。 通用 的 、 标 准 化 的 项 目 目录 结构 。 

。 对 JAR 文件 进行 依赖 管理 。 
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。 统一 的 构建 流程 。 


gradle init 命令 可 以 用 于 对 项 目 进行 初始 化 : 创建 核心 目录 结构 、 初 始 化 构建 脚本 、 提 
供 一 些 简单 的 Java 源 代码 和 测试 代码 。 以 下 是 Gradle 项 目 中 的 一 些 关键 目录 和 文件 。 


。 src/main/ 目录 包含 源 代 码 和 资源 文件 。 
一 java/ 目录 包含 Java 源 代码 。 
— resources/ 目录 包含 源 代码 所 使 用 的 资源 文件 (属性 配置 文件 、JSON 等 数据 文件 ) 。 
。 test/main/ 目录 包含 测试 代码 和 测试 资源 文件 。 
一 java/ 目录 包含 Java 测试 代码 。 
一 resources/ 目录 包含 测试 代码 所 使 用 的 资源 文件 (属性 配置 文件 、JSON 等 数据 文件 )。 
。 build/ 目录 包含 编译 源 代 码 和 测试 代码 后 生成 的 class 文件 。 
一 libs/ 目录 包含 项 目 构建 后 生成 的 JAR 包 和 WAR 包 。 
e gradlew 是 一 个 Gradle 封装 工具 ， 人 允许 以 可 执行 JAR 包 的 方式 运行 项 目 。 对 此 ， 我 们 将 
在 之 后 介绍 Spring Boot 时 进行 详细 的 描述 。 
e build.gradle 文件 由 gradle init 命令 生成 ， 但 其 中 的 项 目 依赖 则 需要 手动 添加 。Gradle 
并 没有 使 用 XML， 而 是 使 用 了 一 种 基于 Groovy 的 领域 专用 语言 来 编写 其 构建 脚本 。 
* build/ 目录 包含 由 gradle build 和 gradle test 命令 所 生成 的 与 构建 相关 的 文件 。 


以 下 是 使 用 Gradle 时 必须 了 解 的 一 些 Gradle 任务 。 可 以 通过 在 命令 行 中 执行 gradle tasks 
来 列举 这 些 任 务 。 
gradle build 
构建 项 目 。 
gradle classes 
编译 Java 源 代 码 。 
gradle clean 


删除 build 目录 。 
gradle jar 
编译 Java 源 代 码 ， 并 将 编译 结果 和 资源 文件 一 同 打包 为 JAR 包 。 
gradle javadoc 
根据 Java 源 代码 生成 JavaDoc 文档 。 
gradle test 
编译 Java 源 代 码 和 测试 代码 ， 然 后 运行 单元 测试 。 
gradle testClasses 
编译 Java 测试 代码 。 
以 下 是 示例 项 目的 创建 过 程 。 
。 使 用 gradle init --type java-application 命令 初始 化 speakers-test 和 speakers-web 应 
用 程序 。 
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。 初始 生成 的 build.gradle 文件 、Java 应 用 程序 和 测试 文件 都 只 是 模拟 的 ， 为 了 运行 本 章 
中 的 示例 ， 它 们 会 被 真实 代码 所 替换 。 

Gradle 的 文档 非常 全 面 ， 以 下 是 用 于 深入 了 解 Gradle 的 一 些 教程 和 参考 资料 ; 

。 Gradle 用 户 指 南 ; 


。 Gradle AT]; 
* Tim Berglund 所 著 Gradle Beyond the Basics (O^ Reilly 出 版 社 ) 。 


了 解 了 Gradle 的 一 些 基 础 知识 后 ， 接 下 来 本 章 会 介绍 Java 中 的 JSON 类 库 ， 然 后 再 看 一 下 
相关 的 代码 示例 。 


4.3 使 用 JUnit 即 可 完成 单元 测试 


JUnit 是 一 个 广泛 使 用 的 单元 测试 框架 。 因 为 在 Java 社区 中 广 为 接受 ， 所 以 本 章 中 的 测试 
都 将 使 用 JUnit 来 编写 。JUnit 是 过 程式 的 ， 因 此 使 用 JUnit 所 编写 的 单元 测试 遵循 的 是 
TDD 风格 。 如 果 需 要 在 JUnit 中 编写 BDD 风格 的 测试 ， 那 么 Cucumber 会 是 一 个 不 错 的 选 
择 。 如 需 学 习 更 多 有 关 BDD 和 Cucumber 方面 的 知识 ， 可 以 参考 Micha Kops 的 一 篇 高 质 
量 文章 “BDD Testing with Cucumber, Java and JUnit” , 


44 _ Java 中 的 JSON 类 库 
Java 中 存在 多 个 不 错 的 JSON 类 库 ， 可 用 于 进行 JSON 的 序列 化 / 反 序 列 化 操作 ， 举 例如 下 。 


Jackson 


可 以 在 Jackson 的 GitHub 主页 上 了 解 到 更 多 细节 信息 。 


Gson 
Gson 是 一 个 由 Google 提供 的 JSON 类 库 。 


JSON-java 
该 类 库 由 Doug Crockford 所 提供 。 


JavaSE (标准 版 ) 
JavaEE 7 以 Java 标准 请 求 (JSR) 353 的 形式 引入 了 对 JSON 的 支持 。JSR-353 是 一 个 单 
独 的 实现 ， 因 此 可 以 将 其 整合 到 已 有 的 Java SE 应 用 程序 中 ， 以 作为 Java SE 8 的 一 部 
分 。 作 为 Java 增强 (JEP) 198 号 提案 的 一 部 分 ，Java SE 9 将 对 JSON 提供 原生 支持 。 


出 于 以 下 原因 ， 本 章 中 的 示例 使 用 的 都 是 Jackson: 


。 在 Java 社区 尤其 是 Spring HXP, Jackson 的 使 用 非常 广泛 ; 
。 可 以 提供 高 质量 的 功能 ， 

。 经 历 过 时 间 的 考验 ， 

。 开发 社区 活跃 ， 项目 维护 较 好 ， 

。 文档 质量 较 高 。 




































































另外 ， 只 使 用 一 种 JSON 类 库 可 以 使 得 我 们 将 注意 力 集 中 于 JSON。 如 上 所 述 ， 其 他 类 库 
也 都 能 很 好 地 工作 ， 因 此 你 可 以 自行 选择 尝试 。 


首先 ， 我 们 来 看 一 下 Java 中 的 一 些 基本 序列 化 / 反 序 列 化 操作 。 


4.5 ”用 Jackson 进 行 JSON 序 列 化 / 反 序列 化 操作 


Java 应 用 程序 需要 能 够 将 Java 数据 结构 转换 为 ON (序列 化 )， 也 需要 能 够 进行 相反 的 
操作 ( 反 序列 化 )。 


4.5.1 uu mnt TUNE 
与 之 前 的 章节 一 样 ， 我 们 先 对 一 些 基本 的 Java 数据 类 型 进行 序列 化 操作 
































。 整数 型 

。 FITR 

。 数组 

。 布尔 值 

例 4-1 展示 了 一 个 简单 的 单元 测试 程序 ， 该 程序 使 用 Jackson 和 JUnit 4 对 Java 中 的 简单 数 
据 类 型 进行 序列 化 / 反 序 列 化 操作 。 


例 4-1  speakers-test/src/test/java/org/jsonatwork/ch4/BasicJsonTypesTest.java 
package org.jsonatwork.ch4; 


import static org.junit.Assert.*; 


import java.io.*; 
import java.util.*; 


import org.junit.Test; 


import com.fasterxml.jackson.core.*; 
import com.fasterxml.jackson.core.type.*; 
import com.fasterxml.jackson.databind.*; 


public class BasicJsonTypesTest { 
private static final String TEST SPEAKER = "age = 39\n" + 
"fullName = \"Larson Richard\"\n" + 
"tags = [\"JavaScript\",\"AngularJS\",\"Yeoman\"]\n" + 
"registered = true"; 


@Test 
public void serializeBasicTypes() { 
try { 

ObjectMapper mapper = new ObjectMapper(); 
Writer writer = new StringWriter(); 
int age = 39; 
String fullName = new String("Larson Richard"); 
List<String> tags = new ArrayList<String>( 
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j 
} 


Arrays.asList("JavaScript", "AngularJS", "Yeoman")); 


boolean registered = true; 
String speaker = null; 


writer.write("age = "); 
mapper.writeValue(writer, age); 
writer .write("\nfullName = "); 
mapper.writeValue(writer, fullName); 
writer.write("\ntags = "); 
mapper.writeValue(writer, tags); 
writer .write("\nregistered = "); 


mapper.configure(SerializationFeature.INDENT OUTPUT, true); 


mapper.writeValue(writer, registered); 
speaker = writer.toString(); 
System.out.println(speaker); 
assertTrue(TEST SPEAKER.equals(speaker)); 
assertTrue(true); 

catch (JsonGenerationException jge) { 
jge.printStackTrace(); 
fail(jge.getMessage()); 

catch (JsonMappingException jme) { 
jme.printStackTrace(); 
fail(jme.getMessage()); 

catch (IOException ioe) { 
ioe.printStackTrace(); 
fail(ioe.getMessage()); 


@Test 
public void deSerializeBasicTypes() { 
try { 


String ageJson = "{ \"age\": 39 }"; 

ObjectMapper mapper = new ObjectMapper(); 

Map<String, Integer» ageMap = mapper.readValue(ageJson, 
new TypeReference<HashMap<String,Integer>>() {}); 


Integer age = ageMap.get("age"); 
System.out.println("age = " + age + "\n\n\n"); 
assertEquals(39, age.intValue()); 
assertTrue(true); 

catch (JsonMappingException jme) { 
jme.printStackTrace(); 

fail(jme.getMessage()); 

catch (IOException ioe) { 
ioe.printStackTrace(); 

fail(ioe.getMessage()); 





在 以 上 示例 中 ， 由 于 aest 注解 的 声明 ，JUnit 会 将 serializeBasicTypes() 和 deSerializeBasicTypes() 
方法 作为 测试 的 一 部 分 来 运行 。 对 于 ISON 数据 自身 来 说 ， 这 些 单元 测试 用 例 并 未 执行 太 
多 的 断言 操作 。 在 介绍 对 Web API 的 测试 工作 时 ， 我 们 会 更 详细 地 探讨 断言 。 

以 下 是 Jackson 中 用 于 JSON 序列 化 / 反 序 列 化 操作 的 一 些 最 重要 的 类 和 方法 。 

e ObjectMapper 类 负责 在 Java 和 JSON 间 进 行 相互 转换 。 

e ObjectMapper .writeValue() 方法 负责 将 Java 数据 类 型 转换 为 ON (在 本 例 中 ， 转 换 结 
果 被 输出 到 Writer 对 象 中 )。 

。 ObjectMapper.readValue() 方法 负责 将 JSON 转换 为 Java 数据 结构 。 

在 命令 行 中 执行 以 下 命令 ， 以 运行 这 一 单元 测试 


cd chapter-4/speakers-test 

































































*gradle test --tests org.jsonatwork.ch4.BasicJsonTypesTest+ 
可 以 看 到 如 下 结果 : 


json-at-work => gradle test --tests org.jsonatwork.ch4.BasicJsonTypesTest 
:compileJava 

:processResources NO-SOURCE 

:classes 

:compileTestJava 

:processTestResources 

:testClasses 

:test 

















org. jsonatwork.ch4.BasicJsonTypesTest > deSerializeBasicTypes STANDARD. OUT 
age - 39 


org. jsonatwork.ch4.BasicJsonTypesTest > serializeBasicTypes STANDARD. OUT 
age - 39 
fullName - "Larson Richard" 
tags = ["JavaScript" , "AngularJS" , "Yeoman" 
registered - true 


BUILD SUCCESSFUL 








因为 只 是 序列 化 / 反 序 列 化 了 简单 的 数据 类 型 ， 所 以 以 上 示例 并 没有 提供 什么 有 意思 的 功 
能 。 但 对 于 Java 对 象 来 说， 序列 化 / 反 序 列 化 操作 就 比较 有 用 了 。 


4.5.2 ”对 Java 对 象 进行 序列 化 / 反 序列 化 操作 


了 解 了 Jackson 以 及 简单 数据 类 型 上 的 Jackson 操作 后 ， 我 们 将 深入 介绍 Jackson 对 对 象 的 
处 理 。 例 4-2 展示 了 如 何 使 用 Jackson 来 序列 化 / 反 序列 化 speaker 对 象 ， 同 时 也 展示 了 如 
何 将 ISON 文件 反 序列 化 为 多 个 speaker HR. 
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f 4-2 speakers-test/src/test/java/org/jsonatwork/ch4/ SpeakerJsonFlatFileTest.java 


package org.jsonatwork.ch4; 
import static org.junit.Assert.*; 


import java.io.*; 
import java.net.*; 
import java.util.*; 


import org.junit.Test; 


import com.fasterxml.jackson.core.*; 
import com.fasterxml.jackson.databind.*; 
import com.fasterxml.jackson.databind.type.*; 


public class SpeakerJsonFlatFileTest { 


private static final String SPEAKER JSON FILE NAME - "speaker.json"; 
private static final String SPEAKERS JSON FILE NAME - "speakers.json"; 
private static final String TEST SPEAKER JSON = "{\n" + 

" \"id\" : 1,\n" + 

" \"age\" : 39,\n" + 

"” \"fullName\" : \"Larson Richard\",\n" + 

" \"tags\" : [ \"JavaScript\", \"AngularJS\", \"Yeoman\" ],\n" + 


" W'registeredV" : true\n" + 
SFS 
QTest 
public void serializeObject() ( 
try { 


ObjectMapper mapper = new ObjectMapper(); 

Writer writer = new StringWriter(); 

String[] tags = {"JavaScript", "AngularJS", "Yeoman"}; 

Speaker speaker = new Speaker(1, 39, "Larson Richard", tags, true); 
String speakerStr = null; 


mapper.configure(SerializationFeature.INDENT OUTPUT, true); 
speakerStr - mapper.writeValueAsString(speaker); 
System.out.println(speakerStr); 
assertTrue(TEST SPEAKER JSON.equals(speakerStr)); 
assertTrue(true); 

} catch (JsonGenerationException jge) { 
jge.printStackTrace(); 
fail(jge.getMessage()); 

} catch (JsonMappingException jme) { 
jme.printStackTrace(); 
fail(jme.getMessage()); 

} catch (IOException ioe) { 
ioe.printStackTrace(); 
fail(ioe.getMessage()); 

} 

} 


private File getSpeakerFile(String speakerFileName) throws URISyntaxException { 





ClassLoader classLoader = Thread.currentThread().getContextClassLoader(); 
URL fileUrl = classLoader.getResource(speakerFileName); 

URI fileUri = new URI(fileUrl.toString()); 

File speakerFile - new File(fileUri); 


return speakerFile; 


} 
@Test 
public void deSerializeObject() { 
try { 
ObjectMapper mapper = new ObjectMapper(); 
File speakerFile = getSpeakerFile( 
SpeakerJsonFlatFileTest.SPEAKER JSON FILE NAME); 
Speaker speaker - mapper.readValue(speakerFile, Speaker.class); 
System.out.println("\n" + speaker + "\n"); 
assertEquals("Larson Richard", speaker.getFullName()); 
assertEquals(39, speaker.getAge()); 
assertTrue(true); 
} catch (URISyntaxException use) { 
use.printStackTrace(); 
fail(use.getMessage()); 
} catch (JsonParseException jpe) { 
jpe.printStackTrace(); 
fail(jpe.getMessage()); 
} catch (JsonMappingException jme) { 
jme.printStackTrace(); 
fail(jme.getMessage()); 
} catch (IOException ioe) { 
ioe.printStackTrace(); 
fail(ioe.getMessage()); 
} 
} 
@Test 
public void deSerializeMultipleObjects() ( 
try { 


ObjectMapper mapper - new ObjectMapper(); 
File speakersFile - getSpeakerFile( 
SpeakerJsonFlatFileTest.SPEAKERS, JSON FILE NAME); 


JsonNode arrNode - mapper.readTree(speakersFile).get("speakers"); 
List<Speaker> speakers = new ArrayList<Speaker>(); 
if (arrNode.isArray()) ( 
for (JsonNode objNode : arrNode) { 
System.out.println(objNode); 
speakers.add(mapper.convertValue(objNode, Speaker.class)); 
} 
} 


assertEquals(3, speakers.size()); 
System.out.println("\n\n\nALl Speakers\n"); 
for (Speaker speaker: speakers) { 





在 Java 中 使 用 JSON 





77 


System.out.println(speaker); 


} 


System.out.println("\n"); 

Speaker speaker3 = speakers.get(2); 
assertEquals("Christensen Fisher", speaker3.getFullName()); 
assertEquals(45, speaker3.getAge()); 

assertTrue(true); 

} catch (URISyntaxException use) { 
use.printStackTrace(); 
fail(use.getMessage()); 

} catch (JsonParseException jpe) { 
jpe.printStackTrace(); 
fail(jpe.getMessage()); 

} catch (JsonMappingException jme) { 
jme.printStackTrace(); 
fail(jme.getMessage()); 

) catch (IOException ioe) ( 
ioe.printStackTrace(); 
fail(ioe.getMessage()); 

} 

} 


} 





对 于 以 上 的 JUnit 单元 测试 ， 以 下 几 点 值得 一 提 。 








serializeObject() 方法 创建 了 一 个 Speaker 对 象 ， 然 后 使 用 ObjectMapper .writeValueAsString() 
和 System.out.printin() 将 其 序列 化 , 并 打印 到 标准 输出 。 测 试 代码 将 SerializationFeature. 














INDENT_OUTPUT 设置 为 true, DRIE ISON 输出 中 的 缩 进 和 显示 。 





deSerializeObject() 方法 调用 getSpeakerFile() 来 读 取 包 含 speaker 对 象 的 JSON 输入 





文件 ， 然 后 使 用 ObjectMapper.readValue() 将 其 反 序 列 化 为 SpeakerJava 对 象 。 
deSerializeMultipleObjects() 方法 执行 了 以 下 操作 。 
— 调用 getspeakerFile() 来 读 取 包 含 speaker 对 象 数组 的 ISON 输入 文件 。 





— 调用 0bjectMapper.readTree() 来 获取 JsonNode 对 象 ， 该 对 象 指向 文件 中 的 JSON XC 





档 的 根 节点 。 


- 访问 ISON 树 中 的 每 个 节点 ， 并 使 用 ObjectMapper.convertValue() 方法 将 节点 中 的 


speaker 数据 反 序 列 化 为 Java 中 的 Speaker 对 象 。 
一 打印 列表 中 的 所 有 Speaker 对 象 。 
getSpeakerFile() 方法 会 查找 类 路 径 中 相应 的 文件 ， 并 执行 以 下 操作 。 
— 从 当前 执行 线程 中 获取 ContextClassLoader 对 象 。 
— 使 用 ClassLoader.getResource() 方法 从 当前 类 路 径 中 查找 相关 文件 资源 。 
— 根据 文件 名 的 URI 创建 File 对 象 。 





之 前 的 测试 用 例 均 使 用 了 JUnit 中 的 断言 方法 来 测试 JSON 序列 化 / 反 序 列 化 的 结果 。 


在 命令 行 中 执行 gradle test --tests org.jsonatwork.ch4.SpeakerJsonFlatFileTest MS, 


ws 


ZIT 


测试 后 可 以 看 到 以 下 结果 : 





json-at-work => gradle test --tests org. jsonatwork.ch4.SpeakerJsonFlatFileTest 
:compileJava UP-TO-DATE 

:processResources NO-SOURCE 

:classes UP-TO-DATE 

:compileTestJava UP-TO-DATE 

:processTestResources UP-TO-DATE 

:testClasses UP-TO-DATE 

:test 


org.jsonatwork.ch4.SpeakerJsonFlatFileTest > serializeObject STANDARD OUT 
age" : 39, 
"fullName" : "Larson Richard", 
"tags" : [ "JavaScript", "AngularJS", "Yeoman" ], 
"registered" : true 
H 
org. jsonatwork.ch4.SpeakerJsonFlatFileTest > deSerializeObject STANDARD OUT 


Speaker [id-1, age-39, fullName-Larson Richard, tags-[JavaScript, AngularJS, Yeoman], registered-true] 


org. jsonatwork. ch4 . Specker]sonFlotFileTest > deSerializeMultipleObjects STANDARD OUT 
:1,"fi :"Larson Richard", "tags" : [" JavaScript", "AngularJS" , "Yeoman" , "age" :39, "registered" :true] 
a "Ester Clements","tags":["REST","Ruby on Rails","APIs"],"age":29,"registered":true} 
S RIE Aea Fisher", "tags": ["Java" , "Spring", "Maven", "REST"] , "age" :45, "registered": false} 


All Speakers 


Speaker [id-1, age-39, fullName-Larson Richard, tags-[JavaScript, AngularJS, Yeoman], registered-true] 
Speaker [id-2, age-29, fullName-Ester Clements, tags-[REST, Ruby on Rails, APIs], registered-true] 
Speaker [id-3, age-45, fullName-Christensen Fisher, tags-[Java, Spring, Maven, REST], registered-false] 





BUILD SUCCESSFUL 








除了 本 章 中 所 介绍 的 内 容 ，Jackson 还 提供 了 很 多 其 他 功能 。 如 需 了 解 更 多 教程 ， 可 参考 
以 下 资源 : 


4. 


到 
fiT 


Eugen Paraschiv 撰写 的 “Java Jackson Tutorial” ; 

Tutorials Point 网 站 提供 的 “Jackson Tutorial" ; 

Pankaj 在 JournalDev 网 站 上 撰写 的 “Jackson JSON Java Parser API Example Tutorial" ; 
Mithil Shah #254) “Java JSON Jackson Introduction" , 


6 用 模拟 API 进 行 单元 测试 


目前 为 止 ， 本 章 中 的 JUnit 测试 代码 所 测试 的 都 是 JSON 静态 文件 中 的 数据 。 接 下 来 我 




















等 针对 API 编写 更 为 实际 的 测试 程序 。 不 过 ， 对 于 待 测试 的 API， 我 们 不 希望 编写 太 多 














代码 ， 也 不 希望 在 基础 架构 上 耗费 大 量 精力 。 本 市 将 展示 在 不 编写 任何 代码 的 情况 下 ， 如 
何 创 建 一 个 能 提供 JSON 响应 的 简单 的 模拟 API。 


4 


























.6.1 测试 数据 





我 们 将 使 用 之 前 章节 中 的 演讲 者 数据 作为 测试 数据 〈 可 在 GitHub 上 找到 )， 并 将 其 部 署 为 
RESTful API， 以 完成 模拟 API 的 创建 工作 。 我 们 会 将 Node.js 模块 json-server 用 作 服 务 
器 ， 向 外 以 Web API 的 形式 暴露 speakers.json 文件 中 的 数据 。 如 需 了 解 json-server 的 安 
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装 ， 可 参考 A.2.5 节 中 的 内 容 。 以 下 是 在 本 地 机 器 中 新 开 命令 行 窗口 来 使 用 5000 端口 运行 
json-server 的 步骤 : 


cd chapter-4/speakers-test/src/test/resources 





json-server -p 5000 ./speakers.json 


访问 该 API 时， 还 可 以 通过 在 URI (如 http://localhost:5000/speakers/1) 中 添加 id 来 获取 
单个 演讲 者 的 数据 。 准 备 好 模拟 API 后 就 可 以 开始 编写 单元 测试 了 。 


4.6.2 用 JUnit 对 API 提 供 的 JSON 进 行 测试 
本 节 的 单元 测试 将 实现 以 下 功能 


。 向 模拟 的 演讲 者 数据 API 发 起 HTTP 调用 ， 
。 检查 HTTP 响应 体 中 的 值 ， 并 将 其 与 预期 结果 进行 对 比 。 


与 之 前 的 章节 一 样 ， 本 节 会 继续 使 用 Unirest 这 一 API 封装 工具 ， 但 在 选择 具体 类 库 时 
使 用 Unirest 的 Java XH. 


在 本 章 前 面 的 JUnit 单元 测试 中 ， 测 试 代 码 仅 检 查 了 最 基本 的 功能 (确保 没有 异常 抛 出 )， 
本 节 将 编写 更 为 复杂 的 单元 测试 用 例 。 以 下 单元 测试 会 检查 HTTP 响应 中 返回 的 ISON 内 
容 ， 校 验 其 是 否 与 预期 结果 一 致 。 对 于 这 一 检查 校 验 工作 ， 我 们 可 以 自行 编写 代码 对 数据 
进行 遍历 比较 ， 也 可 以 使 用 第 三 方 类 库 来 减少 工作 量 。JsonUnit 这 一 类 库 中 就 包含 了 很 多 
有 用 的 匹配 规则 ， 可 以 有 效 简化 JUnit 单元 测试 中 的 JSON 比较 工作 。 在 本 节 的 单元 测试 
中 ， 我 们 会 介绍 JsonUnit 的 一 些 基 本 用 途 ， 但 除了 本 节 示 例 中 所 涉及 的 内 容 外 ，JsonUnit 
还 可 以 提供 更 多 功能 ， 有 具体 包括 : 


。 正则 表达 式 ， 

。 更 多 的 匹配 规则 ; 

。 可 以 忽略 特定 的 字段 。 

例 4-3 中 的 单元 测试 通过 调用 模拟 APT 整合 了 我 们 之 前 所 介绍 的 所 有 内 容 ， 并 比较 了 ISON 
响应 与 预期 结果 。 


例 4-3  speakers-test/src/test/java/org/jsonatwork/ch4/SpeakersJsonApiTest.java 
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package org. jsonatwork.ch4; 
import static org. junit.Assert.*; 


import java.io.*; 
import java.net.*; 
import java.util.*; 


import org.apache.http.*; 
import org. junit.Test; 


import com.fasterxml.jackson.core.*; 

import com.fasterxml.jackson.databind.*; 
import com.mashape.unirest.http.HttpResponse; 
import com.mashape.unirest.http.Unirest; 





import com.mashape.unirest.http.exceptions.*; 
import com.mashape.unirest.request.*; 


import static net.javacrumbs. jsonunit.fluent.JsonFluentAssert.assertThatJson; 


public class SpeakersApiJsonTest { 
private static final String SPEAKERS, ALL URI = "http://localhost:5000/speakers"; 
private static final String SPEAKER 3 URI = SPEAKERS ALL URI + "/3"; 


QTest 
public void testApiAllSpeakersJson() { 


try ( 


String json - null; 
HttpResponse «String» resp - Unirest.get( 
SpeakersApiJsonTest.SPEAKERS ALL URI).asString(); 


assertEquals(HttpStatus.SC OK, resp.getStatus()); 
json = resp.getBody(); 
System.out.println(json); 
assertThatJson(json).node("").isArray(); 
assertThatJson(json).node("").isArray().ofLength(3); 
assertThatJson(json).node("[0]").isObject(); 
assertThatJson(json).node("[0].fullName" ) 
.isStringEqualTo("Larson Richard"); 
assertThatJson(json).node("[0].tags").isArray(); 
assertThatJson(json).node("[0].tags").isArray().ofLength(3); 
assertThatJson(json).node("[0].tags[1]").isStringEqualTo("AngularJS"); 
assertThatJson( json) .node("[0].registered").isEqualTo(true); 
assertTrue(true); 


} catch (UnirestException ue) { 
ue.printStackTrace(); 
} 
} 
@Test 
public void testApiSpeaker3Json() { 
try { 
String json = null; 
HttpResponse <String> resp = Unirest.get( 
SpeakersApiJsonTest.SPEAKER 3 URI).asString(); 
assertEquals(HttpStatus.SC OK, resp.getStatus()); 
json = resp.getBody(); 
System.out.println(json); 
assertThatJson( json).node("").isObject(); 
assertThatJson( json) .node(" fullName") 
.isStringEqualTo("Christensen Fisher"); 
assertThatJson( json).node("tags").isArray(); 
assertThatJson( json).node("tags").isArray().ofLength(4); 
assertThatJson( json).node("tags[2]").isStringEqualTo("Maven"); 
assertTrue(true); 
} catch (UnirestException ue) { 
ue.printStackTrace(); 
} 
} 
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对 于 以 上 单元 测试 ， 需 要 注意 以 下 几 点 。 
e testApiAllSpeakersJson() 测试 用 例 : 


一 使 用 Unirest.get() 方法 调用 http://localhost:5000/speakers， 从 演讲 者 数据 API 中 获 
取 所 有 演讲 者 的 列表 ， 
一 验证 HTTP 响应 状态 码 为 OK (200); 
— 从 HTTP 响应 体 中 获取 包含 speaker 对 象 数 组 的 JSON 文档 ， 
— 使 用 JSONUnit 的 assertThatJson() 方 法 编写 一 系列 断言 语句 对 JSON 文档 进行 校 验 ， 
具体 的 校 验 内 容 如 下 : 
4 JSON 文档 表示 包含 3 个 speaker 对 象 的 数组 ; 
* 每 个 speaker 对 象 中 的 所 有 字段 值 (如 fuLLName，tags 和 registered) 都 符合 预 
期 值 。 
一 运行 gradle test 命令 后 可 以 看 到 以 下 结果 。 
org. jsonatwork.ch4.SpeakersApiJsonTest > testApiAllSpeakersJson STANDARD OUT 
; 1 
"id": 1, 
"fullName": "Larson Richard", 
"tags": [ 


"JavaScript", 


AngularJS", 


"Yeoman" 





























l, 
"age": 39, 
"registered": true 


"registered": false 
} 
] 


BUILD SUCCESSFUL 





e testApiSpeaker3Json() 测试 用 例 : 
— 使 用 Unirest.get() 方 法 调用 http://localhost:5000/speakers/3， 从 演讲 者 数据 API 中 
获取 第 3 个 演讲 者 的 数据 ， 
— Bee HTTP 响应 状态 码 为 OK (200); 
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— M HTTP 响应 体 中 获取 包含 单个 speaker 对 象 的 JSON 文档 ， 








— 使 用 JSONUnit 的 assertThatJson() 方法 编写 一 系列 断言 语句 对 JSON 文档 进行 校 验 ， 
具体 的 校 验 内 容 如 下 : 
4 JSON 文档 表示 单个 的 speaker 对 象 ; 
+ speaker 对 象 中 的 所 有 字段 值 都 符合 预期 ; 

- 运行 gradte test 命令 后 可 以 看 到 以 下 结果 。 





以 上 单元 测试 只 使 用 了 Unirest 中 Java 类 库 的 基本 功能 。 


org. jsonatwork. ch4.SpeakersApiJsonTest > testApiSpeaker3Json STANDARD OUT 
1 


"id": 3 


"fullName": "Christensen Fisher", 


"tags": [ 
"Java", 
"Spring", 
"Maven", 
"REST" 

I, 

"age": 45, 

"registered": false 


提供 了 以 下 特性 : 
。 支持 所 有 的 HTTP 方法 (GET, POST, PUT, DELETE, PATCH) ; 

。 将 HTTP 响应 体 转 换 为 Java 对 象 的 过 程 中 可 以 自 定义 转换 规则 ; 
。 发 送 异 步 (BEI) 请 求 ， 





* 超时 ， 
。 文件 上 传 ， 
。 更 多 功能 。 











如 需 了 解 更 多 信息 ， 可 参考 Unirest Java 类 库 的 官方 网 站 。 





继续 阅读 前 ， 可 








本 节 展 示 了 如 何 





[在 命令 行 中 敲 击 Ctrl-C 来 关闭 json-server, 
部 署 和 调用 模拟 API， 接 下 来 我 们 将 搭建 一 个 小 型 的 RESTful API。 


4.7 用 Spring Boot 搭 建 小 型 Web API 


本 节 将 继续 使 月 


speakers-api), Spring £f 








除 此 之 外 ，Unirest 的 Java 类 库 还 


日 演讲 者 数据 ， 通 过 Spring Boot 将 其 创建 为 API (示例 代码 中 的 chapter-4/ 








匡 架 可 以 简化 Java Web 应 用 程序 和 RESTful API 的 开发 、 部 署 工作 。 


Spring Boot 则 通过 默认 配置 简化 Spring 应 用 程序 的 创建 工作 。 使 用 Spring Boot 可 以 带 来 


以 下 好 处 。 


。 不 再 需要 繁琐 易 错 的 XML 配置 文件 。 
e Tomcat/Jetty 能 够 以 程序 嵌入 的 方式 运行 ， 从 而 避免 单独 部 署 WAR (Web application 


ARchive，Web 应 用 程序 存档 ) 包 。 
包 ， 并 将 其 部 署 到 Tomcat E, [E Ata SER 





























你 仍然 可 以 使 用 Spring Boot 和 Gradle 来 构建 WAR 


i 内 容 所 展示 的 那样 ， 以 可 执行 JAR 包 的 方 











式 运 行 Web 








应 用 程序 可 以 减少 项 


进 应 用 程序 迭代 式 开发 。 

















目 在 搭建 、 


安装 方面 的 工作 ， 从 而 简化 天 


F 发 环境 ， 促 
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我 们 将 通过 以 下 步骤 使 用 Spring Boot 来 创建 并 部 署 演讲 者 数据 APL 
(1) 编写 源 代码 。 








。 模型 
。 控制 器 
。 应 用 程序 


(2) 创建 一 个 构建 脚本 (build.gradle) 。 
(3) 使 用 gradlew 部 署 舱 入 运行 的 JAR 包 。 
(4) 用 Postman 进行 测试 。 


4.7.1 创建 模型 


fill 4-4 中 的 Speaker 类 是 一 个 普通 的 Java 对 象 ， 用 于 表示 演讲 者 数据 ，APTI 则 会 将 这 些 数 
据 以 JSON 的 形式 加 以 呈现 。 


| 4-4  speakers-api/src/main/java/org/jsonatwork/ch4/Speaker.java 
package org.jsonatwork.ch4; 


import java.util.ArrayList; 
import java.util.Arrays; 
import java.util.List; 


public class Speaker { 
private int id; 
private int age; 
private String fullName; 
private List<String> tags = new ArrayList<String>(); 
private boolean registered; 


public Speaker() ( 
super(); 


public Speaker(int id, int age, String fullName, List«String» tags, 
boolean registered) { 
super(); 
this.id - id; 
this.age - age; 
this.fullName - fullName; 
this.tags - tags; 
this.registered - registered; 


} 


public Speaker(int id, int age, String fullName, String[] tags, 
boolean registered) { 
this(id, age, fullName, Arrays.asList(tags), registered); 


} 


public int getId() { 
return id; 





public void setId(int id) ( 


this.id - id 


j 


B 


public int getAge() { 


return age; 


j 


public void setAge(int age) ( 


this.age - a 


j 


public String 
return fullN 


j 


ge; 


getFullName() { 
ame; 


public void setFullName(String fullName) { 
this.fullName - fullName; 


j 


public List«St 
return tags; 


j 


ring» getTags() { 


public void setTags(List<String> tags) { 


this.tags - 


j 


tags; 


public boolean isRegistered() { 
return registered; 


j 


public void setRegistered(boolean registered) ( 
this.registered - registered; 


j 


@Override 
public String 


toString() { 


return String. format( 


"Speaker [ 


id=%s, age=%s, fullName=%s, tags=%s, registered=%s]", 


id, age, fullName, tags, registered); 


} 


除了 为 speaker 对 象 实例 提供 数 








承担 太 多 工作 。 如 后 理 





的 程序 所 示 ，Spring 会 将 该 speaker 对 象 自动 转换 成 JSON， 











述 代码 中 也 不 会 包含 JSON 格式 方面 的 任何 信息 。 


4.7.2 创建 控制 器 


， 控 制 器 负责 接受 HTTP 请 求 并 返回 HTTP 响应。 在 本 节 示 例 中 ， 演 


在 Spring 应 用 程序 中 





讲 者 数据 的 JSON 会 以 HITP 响应 体 的 形式 返 


代码 。 


























大 








因 成 员 、 构 造 器 和 getter/setter 访问 方法 外 ， 以 上 代码 没有 


此 上 


回 。 例 4-5 展示 了 SpeakerController 类 的 源 
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fij 4-5 speakers-api/src/main/java/org/jsonatwork/ch4/SpeakerController.java 
package org.jsonatwork.ch4; 


import java.util.*; 
import org.springframework.web.bind.annotation.*; 
import org.springframework.http.*; 


@RestController 
public class SpeakerController { 


private static Speaker speakers[] = { 
new Speaker(1, 39, "Larson Richard", 
new String[] {"JavaScript", "AngularJS", "Yeoman"}, true), 
new Speaker(2, 29, "Ester Clements", 
new String[] {"REST", "Ruby on Rails", "APIs"}, true), 
new Speaker(3, 45, "Christensen Fisher", 
new String[] {"Java", "Spring", "Maven", "REST"}, false) 


he 


@RequestMapping(value = "/speakers", method = RequestMethod.GET) 
public List<Speaker> getAllSpeakers() { 
return Arrays.asList(speakers) ; 


} 


@RequestMapping(value = "/speakers/{id}", method = RequestMethod.GET) 
public ResponseEntity<?> getSpeakerById(@PathVariable long id) { 
int tempId = ((new Long(id)).intValue() - 1); 
if (tempId >= 0 && tempId < speakers.length) { 
return new ResponseEntity<Speaker>(speakers[tempId], HttpStatus.OK); 


) else { 
return new ResponseEntity(HttpStatus.NOT FOUND); 


j 
} 
j 


关于 这 上段 代码 ， 需 要 注意 以 下 几 点 。 
e @RestController 注解 将 SpeakerController 类 标记 为 处 理 HTTP 请 求 的 Spring MVC 控 
制 器 。 
e speakers 数组 是 硬 编码 的 ， 仅 适用 于 测试 。 真 实 的 应 用 程序 中 会 有 一 个 单独 的 数据 层 负 
责 从 数据 库 中 读 取 speakers 信息 ， 或 者 通过 外 部 API 调用 获取 speakers 数据 。 
e getAllSpeakers() 方法 执行 了 以 下 操作 。 
— 响应 /speakers URI 上 的 HTTP GET 请 求 。 
一 以 ArrayList 的 形式 读 取 整 个 speakers 数组 ， 并 将 其 转换 成 JSON 数组 的 格式 ， 然 
后 以 HTTP 响应 体 的 形式 输出 。 
— @RequestMapping 注解 会 由 getAllSpeakers() 方法 来 处 理 /speakers URI 上 的 GET 请 求 。 
。 getSpeakerById() 方法 执行 了 以 下 操作 。 
— 响应 /speakers/{id} URI (id 表示 演讲 者 的 ID) 上 的 HTTP GET 请 求 。 
— 根据 演讲 者 的 ID 读 取 speaker 对 象 数 据 ， 并 将 其 转换 成 JSON 对 象 的 格式 ， 然 后 以 
HTTP 响应 体 的 形式 输出 。 












































^ 
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— GPathVariable 注解 将 HTTP 请 求 路 径 中 的 演讲 者 ID 用 作 id 参数， 以 查找 相应 的 


speaker 对 象 。 
— 返回 的 ResponseEntity 类 型 可 用 于 设 定 HTTP 响应 状态 码 以 及 响应 中 的 演讲 者 数据 。 


在 上 述 两 个 方法 中 ，Speaker 对 象 都 能 自动 转换 成 JSON， 无 须 任何 额外 工作 。 上 默认 情况 
下 ，Spring 会 使 用 Jackson 来 自动 完成 从 Java 到 JSON 的 转换 操作 。 


4.7.3 注册 应 用 程序 

本 章 前 面 提 到 过 ， 可 以 将 演讲 者 数据 API 打包 成 WAR 包 ， 并 将 其 部 署 到 Tomcat 等 应 用 程 
序 服务 器 上 。 不 过 ， 以 独立 应 用 程序 的 方式 从 命令 行 中 启动 API 会 更 简单 。 具 体操 作 如 下 。 
。 添加 Java 中 的 main 方法 。 

。 将 应 用 程序 打包 为 可 执行 JAR 包 。 

例 4-6 中 的 Application 类 提供 了 我 们 所 需要 的 main() 方法 。 


例 4-6 — speakers-api/src/main/java/org/jsonatwork/ch4/A pplication.java 
package org.jsonatwork.ch4; 

















import org.springframework.boot.SpringApplication; 
import org.springframework.boot.autoconfigure.SpringBootApplication; 


@SpringBootAppLlication 
public class Application { 


public static void main(String[] args) { 
SpringApplication.run(Application.class, args); 


} 
在 以 上 示例 中 ，@SpringBootApplication 注解 在 Spring 上 对 应 用 程序 进行 了 和 注册， 并 完成 
了 SpeakerController 类 与 Speaker 类 的 设 定 。 
以 上 就 是 所 有 的 源 代码 。 接 下 来 我 们 会 介绍 用 于 构建 应 用 程序 的 build. gradle 脚本 。 


4.7.4 编写 构建 脚本 
Gradle 使 用 名 为 build.gradle 的 脚本 文件 来 构建 应 用 程序 。 例 4-7 展示 了 speakers-api 项 目 
中 的 这 一 构建 脚本 。 


例 4-7  speakers-api/build.gradle 


buildscript { 
repositories { 
mavenCentral() 











dependencies { 
classpath("org.springframework.boot:spring-boot-gradle-plugin:1.5.2.RELEASE") 


j 
} 


apply plugin: 'java' 
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apply plugin: 'org.springframework.boot' 


ext { 
jdkVersion = "1.8" 
} 


sourceCompatibility 
targetCompatibility 


jdkVersion 
jdkVersion 


tasks.withType(JavaCompile) { 
options.encoding = 'UTF-8' 


j 


jar { 


baseName = 'speakers-api' 


version = '0.0.1' 


j 


repositories { 
mavenCentral() 


test ( 
testLogging { 
showStandardStreams 


} 





= true // 显示 标准 输出 和 标准 错误 


ignoreFailures = false 


j 


dependencies { 
compile ( 


[group: 'org.springframework.boot', name: 'spring-boot-starter-web'] 


) 
} 


关于 以 上 示例 中 的 build.gradle 脚本 ， 需 要 注意 以 下 几 点 。 


。 Spring Boot 的 Gradle 插件 执行 了 以 下 操作 。 
— 将 所 有 组 件 构 建 为 单个 可 执行 JAR 包 。 
— 在 可 执行 JAR 包 中 从 路 径 src/main/java 处 搜索 包含 main() 方法 的 类 (在 本 例 中 ， 这 
个 类 即 为 Application.java) 来 部 署 API。 
。 jar 这 一 代码 块 定义 了 JAR 包 文 件 的 文件 名 。 
。 在 Gradle 中 声明 repositories 部 分 代码 ， 使 得 应 用 程序 从 Maven 中 心 仓库 拉 取 程序 依 











赖 包 。 














。 在 Gradle 中 声明 testLogging 部 分 代码 ， 使 得 应 用 程序 在 执行 测试 时 显示 标准 结果 输出 


和 标准 错误 输出 。 
。 dependencies 声明 了 speak 


以 上 的 构建 脚本 还 是 比较 简章 








ers-api 项 目 所 依赖 的 JAR 包 。 
和 的 。 除 此 之 外 ，Gradle 还 提供 了 很 多 非常 强大 的 构建 功能 。 








如 需 学 习 更 多 有 关 Gradle 构建 的 知识 ， 可 参考 Gradle 用 户 手册 中 的 “Writing Gradle Build 


Scripts” 部 分 。 


我 们 已 经 介绍 了 构建 脚本 ， 现 在 是 时 候 来 部 署 演讲 者 数据 API 了 。 
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4.7.5 部 署 API 


gradle init 命令 在 创建 speakers-api 项 目 时 会 生成 gradlew 脚本 。 如 需 学 习 更 多 有 关 创 建 
Gradle 项 目的 知识 ， 可 参考 Gradle 用 户 手 册 中 的 “Creating New Gradle Builds” 部 分 。 


通过 执行 以 下 步 又 ，gradlew 脚本 会 组 织 所 有 的 资源 并 简化 部 署 工作 。 


。 调用 build.gradle 脚本 来 构建 应 用 程序 ， 并 使 用 Spring Boot 插件 将 结果 打包 为 可 执行 
JAR 包 。 

。 在 内 婴 的 Tomcat 服 务 器 上 以 可 执行 JAR 包 的 形式 将 演讲 者 数据 API 部 署 到 http://localhost: 
8080/speakers, 


在 speakers-api 目录 中 运行 ./gradlew bootRun 命令 来 部 署 应 用 程序 ， 显 示 日 志 消 息 后 可 以 
看 到 以 下 结果 : 


2017-03-31 16:06:08.975 INFO 23433 --- [ main] org.apache.catalina.core.StandardEngine : Starting Servlet Engine: Apache Tomca 
/8.5.11 

2017-03-31 16:06:09.084 INFO 23433 --- [ost-startStop-1] o.a.c.c.C. [Tomcat]. [localhost]. [/] : Initializing Spring embedded WebAppli: 
ationContext 

2017-03-31 16:06:09.084 INFO 23433 --- [ost-startStop-1] o.s.web.context.ContextLoader : Root WebApplicationContext: initializi 
tion completed in 1288 ms 

2017-03-31 16:06:09.215 INFO 23433 --- [ost-startStop-1] o.s.b.w.servlet.ServletRegistrationBean : Mapping servlet: 'dispatcherServlet" 
of 

2017-03-31 16:06:09.220 INFO 23433 --- [ost-startStop-1] o.s.b.w.servlet.FilterRegistrationBean : Mapping filter: 'characterEncodingFil 
er' to: [/*] 

2017-03-31 16:06:09.221 INFO 23433 --- [ost-startStop-1] o.s.b.w.servlet.FilterRegistrationBean  : Mapping filter: 'hiddenHttpMethodFilt 
r' to: [/*] 

2017-03-31 16:06:09.221 INFO 23433 --- [ost-startStop-1] o.s.b.w.servlet.FilterRegistrationBean : Mapping filter: 'httpPutFormContentFi 
ter' to: [/*] 

2017-03-31 16:06:09.221 INFO 23433 --- [ost-startStop-1] o.s.b.w.servlet.FilterRegistrationBean  : Mapping filter: 'requestContextFilter 
to: [/*] 

2017-03-31 16:06:09.517 INFO 23433 --- [ main] s.w.s.m.m.a.RequestMappingHandlerAdapter : Looking for @ControllerAdvice: org.spl 
ingframework. boot . context . embedded . AnnotationConfigEmbeddedWebApplicationContexte3d0f8e03: startup date [Fri Mar 31 16:06:07 MDT 2017]; 

t of context hierarchy 

2017-03-31 16:06:09.599 INFO 23433 --- [ main] s.w.s.m.m.a.RequestMappingHandlerMapping : Mapped "{[/speakers] ,methods=[GET]}" 
nto public java.util.List«org.jsonatwork.ch4.Speaker» org.jsonatwork.ch4. SpeakerController.getAllSpeakers() 

2017-03-31 16:06:09.600 INFO 23433 --- [ main] s m.m.a.RequestMappingHandlerMapping : Mapped "{[/speakers/{id}] ,methods=[GE 
J}" onto public org.springframework.http.ResponseEntity<?> org. jsonatwork.ch4.SpeakerControl Ler .getSpeakerById(long) 

2017-03-31 16:06:09.604 INFO 23433 --- [ main] s.w.s.m.m.a.RequestMappingHandlerMapping : Mapped "{[/error]}" onto public org.s| 
ringframework.http.ResponseEntity«java.util.Map«java.lang.String, java.lang.Object>> org.springframework.boot.autoconfigure.web.BasicError! 
ontroller.error(javax. servlet.http.HttpServletRequest) 

2017-03-31 16:06:09.605 INFO 23433 --- [ main] s.w.s.m.m.a.RequestMappingHandlerMapping : Mapped "[[/error],produces-[text/html 
}" onto public org.springframework.web.servlet.ModelAndView org.springframework.boot.autoconfigure.web.BasicErrorController.errorHtml( java: 
.servlet.http.HttpServletRequest, javax. servlet.http.HttpServletResponse) 

2017-03-31 16:06:09.643 INFO 23433 --- [ main] o.s.w.s.handler.SimpleUrlHandlerMapping : Mapped URL path [/webjars/**] onto hal 
dler of type [class org.springframework.web.servlet.resource.ResourceHttpRequestHandler] 

2017-03-31 16:06:09.644 INFO 23433 --- [ main] o.s.w.s.handler.SimpleUrlHandlerMapping : Mapped URL path [/**] onto handler of 
type [class org.springframework.web.servlet.resource.ResourceHttpRequestHandler] 

2017-03-31 16:06:09.690 INFO 23433 --- [ main] o.s.w.s.handler.SimpleUrlHandlerMapping : Mapped URL path [/**/favicon.ico] onti 
handler of type [class org.springframework.web.servlet.resource.ResourceHttpRequestHandler] 

2017-03-31 16:06:09.863 INFO 23433 --- [ main] o.s.j.e.a.AnnotationMBeanExporter : Registering beans for JMX exposure on| 
startup 

2017-03-31 16:06:09.934 INFO 23433 --- [ main] s.b.c.e.t.TomcatEmbeddedServletContainer : Tomcat started on port(s): 8080 (http 
2017-03-31 16:06:09.940 INFO 23433 --- [ main] org. jsonatwork.ch4.Application : Started Application in 2.536 seconds 
JW running for 2.922) 

> Building 80% > :bootRur 


LZ 








m 



































4.7.6 用 Postman 测 试 API 

与 第 1 章 中 的 做 法 相同 ， 成 功 运行 演讲 者 数据 API 后 ， 我 们 将 使 用 Postman 对 第 一 个 演讲 
者 的 数据 进行 测试 。 在 Postman 的 GUI 中 执行 以 下 操作 。 

(1) 输 入 URL: http://localhost:8080/speakers/1。 


(2) 在 HTTP 方法 中 选择 GET。 
(3) 点 击 Send 按钮 。 


点 击 按钮 后 ， 可 以 看 到 Postman 中 的 GET 请 求 成 功 运 行 ， 并 获取 了 HTTP 200 (OK) 的 状态 
码 ， 同 时 HTTP 响应 体 文本 框 中 显示 了 演讲 者 的 ISON 数据 ， 如 图 4-1 所 示 。 
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GET http://localhost: 


Authorization 





Type 


:8080/speakers/1 Params Send v 


No Auth 


Body 3) Status: 200 OK 
Pretty JSON 

Li 

2 "id": 1 

3 "age": 39 

4 "fullName": "Larson Richard", 

5 tags": [ 

6 "JavaScript", 

7 "AngularJS", 

8 "Yeoman" 

9 1. 

10 "registered": true 

11 











4-1; 在 Postman 中 使 用 演讲 者 数据 API 


"TEE (i-i tc Ctrl-C 来 关闭 gradlew 程序 。 
正如 之 前 所 描述 的 那样 ， 由 于 省 略 了 以 下 工作 ， 应 用 程序 的 开发 和 部 署 都 得 到 了 简化 。 
。 创建 /修改 web.xml 等 Spring 或 Java EE 中 的 XML 元 数据 配置 。 





。 部 署 WAR 文件 。 
。 安装 Tomcat。 


值得 一 提 的 是 ， 上 述 间 





了 署 步骤 仅 展示 了 如 何 搭建 简单 的 Web API 开发 环境 。 当 在 需要 共享 








的 环境 (测试 环境 、 用 户 验收 环境 、 生 产 环 境 ) 中 进行 操作 时 ， 还 是 需要 将 WAR 包 部 署 





到 应 用 程序 服务 器 中 ， 





从 而 对 应 用 程序 进行 性 能 测试 和 调 优 。 





48 ”本 章 回顾 


本 章 先 描述 了 Java Fil ISON 间 的 简单 转换 工作 ， 然 后 演示 了 如 何 调用 一 个 基于 ISON 的 模 
拟 Web API， 并 通过 JUnit 测试 来 调用 结果 。 最 后 用 Spring Boot 创建 了 一 个 RESTful API, 




















并 用 Postman 对 其 进行 了 测试 。 


4.9 内 容 预 告 


我 们 已 经 介绍 了 JSON 在 多 个 平台 (JavaScript、Ruby on Rails 和 Java) 中 的 基本 使 用 情 
况 ， 接 下 来 的 3 章 将 深入 描述 ISON 生态 系统 : 





。 JSON Schema; 


。 在 JSON 中 进行 搜索 ; 
。 对 JSON 进行 格式 转换 。 





第 5 章 将 介绍 JSON S 
结构 化 和 校 验 。 


chema 的 使 用 ， 有 具体 展示 如 何 使 用 JSON Schema 对 JSON 文档 进行 





^ 
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第 二 部 分 





JSON 生 态 系统 


第 5 章 
JSON Schema 





前 面 几 章 展示 了 JSON 在 几 个 核心 平台 (JavaScript, Ruby on Rails 和 Java) 上 的 基本 使 
用 ， 接 下 来 几 章 将 更 深入 地 介绍 JSON。 对 于 应 用 程序 间 用 于 交换 数据 的 JSON 文档 ， 本 
章 将 展示 如 何 使 用 JSON Schema 来 定义 其 结构 与 格式 ， 有 具体 内 容 包括 ; 


。 JSON Schema 概览 ; 
。 JSON Schema 核心 基础 知识 与 工具 ， 
。 如 何 使 用 JSON Schema 来 设计 和 测试 API。 


逐步 介绍 了 JSON Schema 的 概念 后 ， 我 们 将 在 本 章 的 应 用 示例 中 使 用 JSON Schema 来 设 
计 API。 如 前 言 中 提 到 的 那样 ， 从 第 二 部 分 内 容 开始 ， 所 有 的 示例 都 将 采用 Node.js 来 编 
写 ， 以 控制 章节 篇 幅 。 不 过 事实 上 ，JSON Schema 也 能 在 其 他 平台 上 有 效 工作 。 如 果 尚 未 
安装 Node.js， 那 么 可 以 参考 附录 A 中 的 相关 指导 步骤 来 完成 安装 操作 。 


5.1 JSON Schema 概览 


对 于 JSON Schema， 很 多 架构 师 和 开发 人 员 都 会 感觉 比较 陌生 。 因 此 ， 在 详细 摘 述 JSON 
Schema 的 用 法 前 ， 有 必要 先 了 解 一 下 什么 是 JSON Schema， 它 有 什么 用 ， 为 什么 以 及 何 
时 应 当 使 用 它 。 本 节 将 介绍 JSON Schema 的 标准 规范 ， 并 展示 一 个 简单 的 示例 。 














5.1.1 JSON Schema 是 什么 

JSON Schema 是 对 JSON 文档 / 消息 中 的 内 容 、 结 构 与 格式 的 声明 。JSON Schema 可 以 校 
验 JSON 文档 ， 这 可 能 会 导致 一 些 质 疑 : 难道 普通 的 JSON 校 验方 法 无 法 完全 满足 需求 ? 
遗憾 的 是 ， 因 为 校 验 一 词 包含 了 多 种 含义 ， 所 以 该 问题 的 答案 是 肯定 的 








93 


5.1.2 语法 校 验 与 语义 校 验 

普通 的 JSON 校 验 与 JSON Schema 校 验 的 区 别 在 于 校 验 的 类 型 。 当 使 用 普通 的 JSON 校 

验 时 ， 校 验 的 仅仅 是 ISON 文档 的 语法 。 这 一 校 验 类 型 只 能 确保 文档 的 格式 正确 ( 即 存在 

对 称 的 大 括号 、 键 名 由 双 引 号 括 起 来 等 )， 因 此 称 为 语法 校 验 。 我 们 在 之 前 的 章节 中 通过 

JSONLint 执行 过 这 一 操作 ， 而 各 个 平台 的 ISON 解析 操作 中 也 包含 了 该 语法 校 验 的 内 容 。 

JSON Schema 的 作用 

采用 语法 校 验 是 一 个 不 错 的 开始 ， 但 有 时 我 们 需要 通过 语义 校 验 对 JSON 进行 更 深层 次 的 

检查 。 设 想 以 下 场景 。 

。 作为 API 的 使 用 者 ， 你 需要 检查 API 的 ISON 响应 ， 以 确保 其 包含 有 效 的 Speaker 或 者 
Orders 列表 。 

。 作为 API 的 提供 者 ， 你 需要 检查 调用 请 求 中 的 JSON， 以 确保 其 仅 包 含 需要 的 字段 。 

。 你 需要 检查 数据 格式 ， 例 如 ， 检 查 电话 号 码 、 日 期 /时 间 、 邮 政 编 号 、 电 子 邮箱 、 信 用 


卡号 码 等 。 


JSON Schema 可 以 在 上 述 场景 中 大 显 身手 ， 相 应 的 校 验 类 型 称 为 语义 校 验 。 除 了 检查 语 
法 ， 这 种 校 验 方式 还 会 验证 数据 的 含义 。 因 为 可 以 帮助 定义 接口 ， 所 以 采用 JSON Schema 
对 API 的 设计 来 说 也 是 大 有 神 益 的 ， 本 章 后 面 将 对 此 进行 具体 介绍 。 


5.1.3 简单 示例 


探讨 JSON Schema 的 详细 内 容 前 ， 我 们 先 研究 一 下 例 5-1， 以 便 对 ISON Schema 的 语法 有 
个 感性 认 知 。 
例 5-1 ex-1-basic-schema.json 
{ 

"Sschema": "http://json-schema.org/draft-04/schema#", 

"type": "object", 

"properties": { 

"email": { 
"type": "string" 






































"FirstName": { 
"type": "string" 


"LastName": { 
"type": "string" 
} 
} 
} 


以 上 示例 中 的 Schema 声明 了 JSON 文档 中 包含 3 个 字段 (email, firstName 和 | lastName), 
每 个 字段 的 值 均 为 字符 串 。 本 节 会 忽略 该 Schema 的 具体 语法 ， 但 请 放心 ， 本 章 后 面 会 对 
语法 进行 详细 描述 。 例 5-2 展示 了 与 上 述 Schema 对 应 的 一 个 JSON 实例 。 
































例 5-2 ex-1-basic.json 
{ 


"email": "Larsonrichard@ecratic.com", 
"firstName": "Larson", 
"LastName": "Richard" 


} 


5.1.4 Web 上 的 JSON Schema 资源 


对 于 与 JSON Schema 有 关 的 一 切 资源 ， 图 5-1 所 示 网 站 是 最 好 的 着 手 点 。 该 网 站 包含 了 大 
量 的 文档 和 示例 。 





[JSON Schema and Hyper- X 


fi |^ 





json-schema.org 
The home of JSON Schema 


about examples software 





What does it do? 


JSON Schema describes your JSON data format 
JSON Hyper-Schema turns your JSON data into hyper-text 
Advantages 


JSON Schema 
* describes your existing data format 
* clear, human- and machine-readable documentation 
* complete structural validation, useful for 
o automated testing 
o validating client-submitted data 
JSON Hyper-Schema 
* describes your existing API - no new structures required 
e links (including URI Templates for target URIs) 
* forms - specify a JSON Schema for the desired data 





Interested? Check out: 


e the specification 
* some examples 
e this excellent guide for schema authors, from the Space Telescope Science Institute 











图 5-1: json-schema.org 网 站 


你 可 以 在 该 网 站 上 找到 Schema 示例 、 主 流 平台 上 的 高 质量 校 验 类 库 ， 以 及 维护 JSON 
Schema 标准 的 GitHub 主页 ， 如 图 5-2 所 示 。 
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Qison-schema/json-schems x 





fi | & GitHub, Inc. [US]| https://github.com/json-schema/json-schema p 


GitHub This repository Explore Features Enterprise Blog Sign up Sign in 





json-schema / json-schema @watch 71 W Star 535 — V Fork 118 


forked from kriszyp/json-schema 


JSON Schema specifications http://json-schema.org/ 


<> Code 
117 commits 4 branches 2 releases 14 contributors 
Q Issues ^ 
[5 branch: mastery | json-schema / = 
Î Pull requests 4 
This branch ls 50 commits ahead of kriszyp:master 62 Compare 
z sd Wiki 
Merge pull request #163 from APIs-guru/format-fix == 
(@ geraintiutt authored on May 8 latest commit 472c32b8c3 E& 
^ Pulse 
iin draft-00 Schema URIs are now namespace versioned. 5 years ago 
fin draft-01 Schema URIs are now namespace versioned 5 years ago sh Graphs 
lin draft-02 Schema URls are now namespace versioned. 5 years ago 
HTTPS clone URL 
iin draft-03 Fix hyper-schema syntax error. 4 years ago https://github.cos/: | E 
iin draft-04 Draft4: added "format" validation. 2 monthsago You can clone with HTTPS or 
Subversion. © 
lili old Move old specs to old/ directory 2 years ago 
一 Clone in Desktop 
& README.md README updates 2 years ago 


Q Download ZIP 
README.md 











5-2; json-schema 的 GitHub 主页 


可 以 在 GitHub 主页 上 查看 JSON Schema 标准 的 更 新 、 问 题 列 表 以 及 最 新 进展 (具体 详情 
参见 5.1.7 节 )。 


5.1.5 为 什么 使 用 JSON Schema 

JSON Schema 可 用 于 校 验 ISON 文档 的 内 容 和 语义 ， 以 下 是 实际 应 用 中 的 一 些 例子 。 

安全 
开放 式 Web 应 用 程序 安全 项 目 (Open Web Application Security Project, OWASP) 的 
Web Service 安全 速 查 表 建 议 :， Web Service 应 当 使 用 Schema 来 校 验 服务 请 求 中 的 数据 。 
诚然 ， 上 述 文档 中 谈论 的 是 XML Schema， 但 这 一 建议 背后 的 考虑 对 JSON 来 说 也 是 适 
HÉJ. OWASP 号 召 校 验 字段 长 度 (最 小 值 /最 大 值 ) 以 及 字段 格式 (如 电话 号 码 、 邮 

编 )， 以 提高 服务 的 安全 性 。 

消息 设计 
JSON 的 应 用 已 经 不 再 局 限于 API 领域 。 在 Apache Kafka 这 样 的 消息 系统 (第 10 章 将 
对 此 进行 详细 介绍 ) 中 ， 很 多 企业 会 将 JSON 作为 首选 的 数据 交换 格式 。 在 消息 系统 的 
这 种 架构 风格 中 ,消息 的 提供 者 和 使 用 者 是 彻底 解 而 的 ， 而 ISON Schema 可 以 确保 使 
用 者 收 到 格式 正确 的 消息 。 

API 设计 
JSON 可 以 说 是 API 设计 领域 的 “一 等 公民 ”。 通 过 声明 数据 文档 的 格式 、 内 容 和 结构 ， 
JSON Schema 可 以 帮助 定义 API 协议 。 

















原型 制作 

由 于 JSON Schema 的 结构 化 和 严谨 性 ， 使 用 JSON Schema 来 制作 原型 听 上 去 似乎 有 些 
违反 直觉 。 在 本 章 后 面 设 计 API 时 ， 我 们 将 展示 如 何 通过 JSON Schema 及 相关 工具 来 
改进 原型 制作 流程 。 


5.1.6 我 在 JSON Schema 上 的 经 历 


如 前 言 中 提 到 的 ，2009 年 时 我 并 不 确定 企业 是 否 适合 采用 JSON。 那 时 的 我 喜欢 ISON 的 高 
效 与 简洁 ， 但 无 法 确保 应 用 程序 间 交 换 的 ISON 文档 的 结构 与 内 容 。 不 过 ,在 2010 年 了 解 
了 JSON Schema 后 ， 我 就 改变 了 观点 ， 开 始 考虑 将 ISON 作为 企业 级 数据 格式 的 可 行 性 。 


























5.1.7 JSON Schema 标准 的 现状 


截至 本 书 英文 版 出 版 :JSON Schema 标准 规范 的 版 本 是 实现 草案 4 (v0.4), 而 下 一 个 实现 
草案 (v0.6) 也 正在 制订 中 。 草 案 $ (v0.5) 版 本 于 2016 年 年 底 发 布 ， 这 一 草案 只 是 收 
集 了 一 些 工 作 进展 ， 因 此 只 是 一 个 工作 草案 ， 而 非 实 现 草案 。JSON Schema 的 版 本 号 是 
0x， 但 完全 没 必要 对 此 有 所 顾虑 。 从 本 章 的 示例 中 可 以 看 到 ，JSON Schema 十 分 健壮 ， 可 
以 提供 可 靠 的 校 验 功 能 ， 所 有 的 主流 编程 平台 上 也 都 有 大 量 的 ISON Schema 类 库 可 用 。 如 
需 了 解 更 多 细节 ， 可 参考 JSON Schema 草案 4 的 标准 规范 。 
































5.1.8 JSON Schema 与 XML Schema 
除了 以 下 几 点 ，JSON Schema 在 JSON 中 的 作用 与 XML Schema 在 XML 文档 中 的 作用 相同 : 


。 JSON 文档 不 会 引用 JSON Schema, 根据 Schema 校 验 JSON 文档 的 操作 由 应 用 程序 负责 ， 
。 JSON Schema 不 包含 命名 空间 ; 
。 JSON Schema 文件 的 扩展 名 为 .json。 


5.2 JSON Schema 核心 基础 知识 与 工具 


我 们 已 经 概览 过 ISON Schema,， 现 在 是 时 候 对 其 进行 更 深入 的 介绍 了 。JSON Schema 功能 
强大 ， 但 显得 繁琐 单调 ， 因 此 本 节 将 介绍 一 些 工具 来 简化 相关 工作 。 之 后 我 们 会 介绍 一 些 
基础 的 数据 类 型 与 核心 关键 词 ， 以 便 为 实际 项 目 中 使 用 JSON Schema 夯实 基础 。 


























5.2.1 JSON Schema 工作 流 与 工具 

JSON Schema 的 语法 可 能 有 些 令 人 导 步 ， 但 事实 上 开发 人 员 可 以 使 用 一 些 优秀 的 工具 来 简 
化 相关 工作 ， 无 须 手 动 编写 所 有 代码 。 

1. JSON Editor Online 

第 1 章 已 介绍 过 JSON Editor Online， 但 该 工具 值得 我 们 再 次 进行 简要 说 明 。 我 们 可 以 使 用 
JSON Editor Online 对 JSON 文档 进行 建 模 ， 从 而 对 将 要 构建 的 数据 有 个 感性 的 认 知 ， 也 可 














HE 1: 截至 本 书 中 文 版 出 版 ，JSON Schema v0.7 版 本 已 于 2017 年 11 月 19 日 发 布 。 一 一 译 者 注 
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以 使 用 这 一 工具 来 生成 JSON 文档 ， 从 而 避免 大 量 的 手工 输入 操作 。 完 成 JSON 文档 的 生 
成 工作 后 ， 可 以 将 JSON 保存 到 剪贴 板 中 。 


2. JSONSchema.net 

确定 JSON 的 核心 设计 后 ， 即 可 基于 前 面 JSON Editor Online 所 创建 的 JSON 文档 ， 使 用 
JSONSchema.net 应 用 程序 来 生成 JSON Schema (如 图 5-3 所 示 )“。 在 创建 Schema 的 过 程 
中 ， 单 是 使 用 JSONSchema.net 应 用 程序 即 可 节省 80% 的 手工 输入 工作 。 在 进行 Schema 
相关 工作 时 ， 我 总 是 以 使 用 ISONSchema.net 应 用 程序 为 开端 ， 之 后 再 逐步 修缮 。 








@ © ® / Bison schema Generator x 





€ Q fi D jsonschema.net/#/ 





JSONSchema.net Home About Contact ^ Resources Previous Version 


JSON Schema 
URL http://jsonschema.net Edit View | String View 
JSON 1 E 


"$schema": "http://json-schema.org/draft-04/schema&" , 
"address": { Her vp 


"streetAddress": "21 2nd Street", 
"city": "New York" 





"http: //jsonschema.net/address" , 
"type": "object", 
"properties": { 
"streetAddress": ( 
"id": "http://jsonschema.net/address/streetAddress", 
} "type": "string" 
] 3, 


"phoneNumber": [ 


"location": "home", 
"code": 44 


} 





ci { 
"id": "http://jsonschema.net/address/city" , 
"type": "string" 


Well done! You provided valid JSON. } 


"required": [ 


"streetAddress", 


1 


- + 
Include metadata keywords * 
Metadata iu yw “phoneNumber”: { 
"i "http: //jsonschema .net/phoneNumber" , 
General Include default values 'array", 







Values are takan from JSON. http://jsonschema.net/phoneNumber/O" , 


Restrict values to enum 
Uses the default value and null BN Š 
: "http://jsonschema .net/phoneNumber/0/location", 
Use absolute IDs PREDA 
Force required "code": { 

"id": "http://jsonschema.net/phoneNumber/@/code" , 











5-8: JSONSchema.net 中 的 演讲 者 数据 Schema 


以 下 是 使 用 JSONSchema.net 生成 初始 Schema 的 步骤 。 
(在 左 侧 输 入 框 中 粘贴 ISON 文档 。 
(2) 使 用 默认 设置 ， 并 进行 以 下 变更 。 

* XH] “Use absolute IDs" , 

* XH] “Allow additional properties" , 

。 关闭 “Allow additional items” , 








(3) 点 击 Generate Schema 按钮 。 
(4) 将 生成 的 Schema 复制 到 剪贴 板 中 。 




















iE 2: 由 于 JSONSchema.net 网 站 已 改版 ， 因 此 相关 的 截图 和 操作 步骤 已 不 再 ; 














= 
= 
* 
hi 
E 





























3. JSON Validate 
创建 JSON Schema Ja, JSON Validate 应 用 程序 可 以 根据 该 Schema 来 校 验 ISON 文档 ， 如 
5-4 所 示 。 








€ > C fi D jsonvalidate.com 


JSON Validate 








JSON Schema JSON Content 











References (11(21(3)(4](5](6](7](8] Resuts 
a va 
" Learn more about 














图 5-4: jsonvalidate.com 中 合法 的 演讲 者 数据 Schema 


可 以 使 用 Schema 来 校 验 ISON 文档 ， 有 具体 步骤 如 下 所 示 。 


(1) 4 ISON 文档 和 Schema 粘贴 到 JSON Validate 应 用 程序 中 的 相应 地 方 。 
(2) 由 于 已 经 不 再 需要 id 字段 ， 因 此 需 从 Schema 中 将 其 全 部 删除 。 
(3) 点 击 Validate 按钮 来 校 验 文档 。 


4. 在 命令 行 界面 使 用 的 NPM 模 块 : validate 和 jsonlint 

以 上 在 线 工 具 都 需要 恨 好 的 网 络 连接 ， 但 这 一 点 有 时 很 难 做 到 ， 因 此 拥有 可 以 在 本 地 运行 
的 工具 就 显得 非常 重要 。 另 外 ， 如 果 数 据 中 包含 敏感 信息 ， 那 么 在 本 机 命令 行 界 面 中 运 
行 会 更 加 安全 。validate 模块 相当 于 Node.js 中 的 jsonvalidate.com 网 站 。 如 需 安装 并 运行 
validate 模块 ， 可 参考 A.2.5 节 中 的 内 容 。 

jsonvalidate.com 网 站 和 validate 模块 都 是 “Using JSON Schema” 项 目的 一 部 分 ， 该 项 
目 提供 了 非常 不 错 的 Schema 资源 ， 可 以 在 GitHub 上 找到 其 主页 。 第 1 章 中 曾经 介绍 过 
JSONLint 网 站 ， 事 实 上 JSONLint 还 可 以 通过 jsonlint 这 一 Node.js 模块 在 命令 行 中 运行 。 
如 需 安装 并 运行 jsonlint 模块 ， 可 参考 A.2.5 节 中 的 内 容 。 

我 一 般 只 使 用 jsontint 模块 的 语法 校 验 功能 ， 但 如 果 在 命令 行 中 运行 jsonLint --heLp， 就 
可 以 看 到 该 模块 也 支持 Schema 语义 校 验 。 如 需 了 解 更 多 信息 ， 可 参考 jsonlint 在 GitHub 
上 的 文档 。 

我 们 将 在 命令 行 中 使 用 validate 模块 来 运行 接 下 来 的 示例 。 
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5.2.2 ”核心 关键 词 
以 下 是 JSON Schema 中 的 核心 关键 词 。 


Sschema 

声明 遵循 的 JSON Schema 标准 的 版 本 。 例 如 ,"$schema" : "http://json-schema.org/draft-04/ 
schema#" 声明 了 所 属 的 schema 遵循 0.4 版 本 的 JSON Schema 标准 ，http://json-schema. 

org/schena 则 向 JSON 校 验 器 声明 所 属 的 schema 遵循 的 是 当前 最 新 的 标准 版 本 (撰写 
本 书 时 ， 该 版 本 为 0.4) 。 因 为 某 些 ISON 校 验 器 默认 采用 老 版 本 的 ISON Schema, 
最 新 版 的 标准 ， 所 以 使 用 http://json-schema.org/schema 具有 一 定 的 风险 。 为 保险 起 
见 ， 建 议 在 $schema 中 始终 声明 具体 的 Schema 版 本 ， 以 便 JSON 文档 和 JSON 校 验 器 
确定 版 本 信息 。 


type 
声明 某 个 字段 的 数据 类 型 ， 如 "type": "string", 


properties 


声明 对 象 中 的 字段 ， 其 中 包含 具体 字段 的 type 信息 。 


5.2.3 ”基础 类 型 
f| 5-3 中 的 文档 包含 了 前 面 介 绍 的 ISON 中 的 一 些 基 础 数据 类 型 (如 字符 串 、 数 值 、 布 尔 值 )。 


例 5-3 ex-2-basic-types.json 
t 


"email": "Larsonrichard@ecratic.com", 
"firstName": "Larson", 
"lastName": "Richard", 
"age": 39, 
"postedSlides": true, 
"rating": 4.1 
} 


与 第 1 EH AY ISON BD Ac Hee (string, number, array, object, boolean, null) 一 
样 ， i Schema 使 用 了 相同 的 基础 数据 类 型 ， 但 添加 了 integer 类 型 来 表示 整数 。number 
类 型 含义 不 变 ， 仍然 表示 整数 以 及 浮 点 数 。 


例 5-4 中 的 JSON Schema 描述 了 例 5-3 中 的 ISON 文档 结构 。 


例 5-4 ex-2-basic-types-schema.json 






































"$schema": "http://json-schema.org/draft-04/schema#", 
"type": "object", 
"properties": { 
"email": { 
"type": "string" 
"firstName": { 
"type": "string" 
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"LastName": { 
"type": "string" 


age": { 
"type": "integer" 
}, 
"postedSlides": { 
"type": "boolean" 
}, 
"rating": { 
"type": "number" 
} 
} 
} 


在 以 上 示例 中 ， 需 要 注意 以 下 几 点 。 


。 $schema 字段 声明 该 schema 遵循 的 是 JSON Schema v0.4， 因 此 校 验 ISON 文档 时 ， 应 该 
使 用 v0.4 版 本 的 规则 。 

。 第 一 个 type 字段 声明 ISON 文档 的 根 节 点 为 对 象 ， 该 对 象 中 包含 了 所 有 的 文档 字段 。 

。 email, firstName, lastName 字段 的 类 型 是 string, 

e age 的 类 型 为 integer。 虽 然 ISON 本 身 只 支持 number 类 型 ， 但 JSON Schema 在 此 基础 
上 增加 了 更 细 粒 度 的 integer 类 型 。postedSLides 的 类 型 为 boolean, rating 的 类 型 为 
number ， 因 此 可 以 接受 浮 点 数 。 


使 用 validate 运行 以 上 示例 ， 可 以 看 到 对 于 例 5-4 中 的 Schema 来 说 ，JSON 文档 是 合法 的 。 


json-at-work => validate ex-2-basic-types.json ex-2-basic-types-schema. json 
JSON content in file ex-2-basic-types.json is valid 





























json-at-work => fj 


虽然 上 述 Schema 的 使 用 是 一 个 不 错 的 开端 ， 但 对 实际 应 用 来 说 还 远 远 不 够 。 接 下 来 我 们 
对 需要 校 验 的 ISON 文档 进行 一 些 修改 。 


。 增加 额外 字段 ， 如 company, 
。 移 除 一 个 期 望 字段 ， 如 postedSlides, 


Bil 5-5 展示 了 修改 后 的 ISON 文档 。 
f| 5-5  ex-2-basic-types-invalid.json 








{ 
"email": "Larsonrichard@ecratic.com", 
"firstName": "Larson", 
"LastName": "Richard", 
"age": 39, 
"rating": 4.1, 
"company": "None" 


} 
运行 命令 后 可 以 看 到 ， 经 过 以 上 修改 ， 文 档 校 验 结果 还 是 合法 的 。 


json-at-work => validate ex-2-basic-types-invalid.json ex-2-basic-types-schema. json 
JSON content in file ex-2-basic-types-invalid.json is valid 





json-at-work => fj 
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基础 类 型 校 验 

至 此 ， 你 可 能 会 觉得 ISON Schema 没什么 用 处 ， 毕 竞 上 述 校 验 命令 并 未 如 预期 般 工 作 。 但 
通过 增加 一 些 简 单 的 限制 条 件 ， 就 可 以 使 校 验 过 程 像 预期 那样 进行 了 了。 首先， 可 以 像 例 
5-6 中 的 代码 一 样 ， 禁 止 JSON 中 出 现 额外 字段 。 














例 5-6 ex-3-basic-types-no-addl-props-schema.json 
{ 
"$schema": "http://json-schema.org/draft-04/schema#", 
"type": "object", 
"properties": ( 
"email": { 
"type": "string" 
"FirstName": { 
"type": "string" 


Ts 

"LastName": { 
"type": "string" 

F; 


"postedSlides": { 
"type": "boolean" 


}, 
"rating": { 
"type": "number" 
} 
IF 
"additionalProperties": false 


} 
在 以 上 示例 中 ， 将 additionalProperties 设置 为 false 可 以 禁止 ISON 文档 的 根 节 点 对 象 
中 出 现 额 外 字段 。 将 之 前 的 ISON 文档 (ex-2-basic-types-invalid.json) 复制 为 一 个 新 文件 
(ex-3-basic-types-no-addl-props-invalid.json) ， 然 后 再 使 用 之 前 的 Schema 进行 校 验 ， 应 该 可 









































以 看 到 以 下 结果 : 


json-at-work => validate ex-3-basic-types-no-addl-props-invalid.json ex-3-basic-types-no-addl-props-schema. json 
Invalid: Additional properties not allowed 


JSON Schema element: /additionalProperties 
JSON Content path: /age 


与 上 一 次 校 验 的 结果 相 比 ， 这 一 结果 好 多 了 。 然 而 ， 因 为 无 法 确保 文档 中 包含 所 有 的 预期 
字段 ， 所 以 这 一 结果 也 并 不 是 我 们 最 终 想 要 的 。 为 了 在 语义 校 验 上 达到 核心 水 平 ， 需要 确 
保 JSON 中 包含 所 有 的 必需 字段 ， 如 例 5-7 所 示 。 


例 5-7 ex-4-basic-types-validation-req-schema.json 
{ 
"Sschema": "http://json-schema.org/draft-04/schema#", 
"type": "object", 
"properties": { 
"email": { 
"type": "string" 
]， 


"FirstName": { 
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"type": "string" 
"LastName": { 

"type": "string" 
"postedSlides": { 

"type": "boolean" 
"rating": { 

"type": "number" 


}, 
"additionalProperties": false, 
"required": ["email", "firstName", "lastName", "postedSlides", "rating" ] 


} 
在 以 上 示例 中 ，required 数组 声明 所 有 的 必需 字段 ，JSON 文档 则 必须 包含 这 些 字 段 ， 否 
则 即 为 非法 。 值 得 注意 的 是 ， 如 果 某 个 字段 不 在 required 数组 中 ， 则 意味 着 该 字段 属于 可 
选 字段 。 
ill 5-8 展示 了 需要 校 验 的 修改 后 的 ISON 文档 ， 该 文档 缺失 必需 的 rating 字段 而 多 出 了 一 
个 age 字段 。 




















f| 5-8 ex-4-basic-types-validation-req-invalid.json 


{ 
"email": "Larsonrichard@ecratic.com", 
"firstName": "Larson", 
"LastName": "Richard", 
"postedSlides": true, 
"age": 39 

} 





在 命令 行 中 运行 后 可 以 看 到 ， 该 文档 的 校 验 结果 为 非法 ; 


json-at-work => validate ex-4-basic-types-validation-req-invalid.json ex-4-basic-types-validation-req-schema. json 
Invalid: Missing required property: rating 





JSON Schema element: /required/4 
JSON Content path: 




















最 终 ， 我 们 得 到 了 预期 的 校 验 结果 。 


。 禁止 出 现 额 外 的 字段 。 
。 Schema 中 的 所 有 字段 都 是 必需 的 。 


介绍 了 基本 的 语义 校 验 后 ， 我 们 来 看 一 下 JSON 文档 中 的 数值 校 验 操作 。 


5.2.4 数值 

你 可 能 还 记得 ，JSON Schema 中 的 number 类 型 既 可 以 表示 浮 点 数 ， 也 可 以 表示 整数 。 例 
5.9 中 的 Schema 术 验 了 演讲 者 在 会 议 报告 方面 的 平均 评分 rating)， 设 定 其 范围 为 10 
( 极 差 ) -5.0 (RE). 
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例 5-9 ex-5-number-min-max-schema.json 
{ 
"$schema": "http://json-schema.org/draft-04/schema#", 
"type": "object", 
"properties": { 
"rating": { 
"type": "number", 
"minimum": 1.0, 
"maximum": 5.0 
} 
}， 
"additionalProperties": false, 
"required": ["rating"] 


) 
根据 该 Schema, fij 5-10 中 的 ISON 文档 是 合法 的 ， 因 为 其 rating 值 在 1.0-5.0 这 一 范围 内 。 











例 5-10 ex-5-number-min-max.json 


{ 
"rating": 4.99 


} 
例 5-11 中 的 JSON 文档 则 是 非法 的 ， 因 为 其 rating 值 超过 了 5.0. 


f 5-11 ex-5-number-min-max-invalid.json 


{ 


"rating": 6.2 





} 
在 命令 行 中 校 验 例 5-11 中 的 文档 后 ， 可 以 看 到 校 验 结果 为 非法 : 


json-at-work => validate ex-5-number-min-max-invalid.json ex-5-number-min-max-schema. json 
Invalid: Value 6.2 is greater than maximum 5 


B 


JSON Schema element: /properties/rating/maximum 
JSON Content path: /rating 





5.2.5 ”数组 

可 以 使 用 JSON Schema 来 校 验 数 组 。 数 组 中 可 以 包含 JSON Schema 的 任意 基础 类 型 
(string, number, array, object, boolean 和 null), j 5-12 中 的 Schema 会 校 验 tags ^E 
段 ， 设 定 其 为 字符 串 数组 。 

例 5-12 ex-G-array-simple-schema.json 


{ 
"Sschema": "http://json-schema.org/draft-04/schema#", 
"type": "object", 
"properties": ( 








"tags": { 

"type": "array", 
"items": { 
"type": "string" 

} 

} 





}， 
"additionalProperties": false, 
"required": ["tags"] 


根据 以 上 示例 中 的 Schema, (ji 5-13 中 的 ISON 文档 是 合法 的 。 
例 5-13  ex-G-array-simple.json 





"tags" : ["fred"] 











例 5-14 中 的 JSON 文档 则 是 非法 的 ， 因 为 其 tags 数组 中 包含 整数 。 
f| 5-14  ex-6-array-simple-invalid.json 











"tags": ["fred", 1] 
} 


在 命令 行 中 校 验 例 5-14 中 的 文档 ， 可 以 看 到 校 验 结果 为 非法 : 


json-at-work => validate ex-6-array-simple-invalid.json ex-6-array-simple-schema. json 
Invalid: invalid type: number (expected string) 





JSON Schema element: /properties/tags/items/type 
JSON Content path: /tags/1 


JSON Schema 还 可 以 校 验 数组 成 员 的 数目 ， 设 定 最 小 数目 (minItem) 和 最 大 数目 (maxItem), 


























例 5-15 中 的 Schema 会 校 验 tags 数组 ， LEX 2-4, 


例 5-15  ex-7T-array-min-max-schema.json 
{ 
"Sschema": "“http://json-schema.org/draft-04/schema#", 
"type": "object", 
"properties": ( 
"tags": { 
"type": "array", 
"minItems": 2, 
"maxItems": 4, 
"items": { 
"type": "string" 


} 
}, 
"additionalProperties": false, 
"required": ["tags"] 


} 
根据 该 Schema， 例 5-16 中 的 ISON 文档 是 合法 的 。 


例 5-16  ex-7-array-min-max.json 
{ 
"tags": ["fred", "a"] 
} 


例 5-17 中 的 ISON 文档 则 是 非法 的 ， 因 为 其 tags 数组 中 包含 了 5 个 成 员 。 
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例 5-17  ex-T-array-min-max-invalid.json 


{ 
"tags": ["fred", a "x", "betty", "alpha"] 





j 
E 命 令 行 中 进行 校 验 ， 可 以 看 到 结果 为 非法 : 


B 





json-at-work => validate ex-7-array-min-max-invalid.json ex-7-array-min-max-schema. json 
Invalid: Array is too long (5), maximum 4 


JSON Schema element: /properties/tags/maxItems 
JSON Content path: /tags 


5.2.6” 枚 举 值 


通过 在 数组 中 定义 几 个 固定 的 枚 举 值 ，enum 关键 词 可 以 限制 字段 的 取 值 。 例 5-18 中 的 
Schema 限制 了 tags 数组 成 员 的 值 ， 限 定 其 为 "0pen Source", "Java", "JavaScript", 
"JSON" 或 "REST" 中 的 一 个 。 


例 5-18 ex-8-array-enum-schema.json 
"$schema": "http://json-schema.org/draft-04/schema#", 
"type": "object", 
"properties": ( 
"tags": { 

"type": "array", 

"minItems": 2, 

"maxItems": 4, 














"items": { 
"enum": [ 
"Open Source", "Java", "JavaScript", "JSON", "REST" 
] 
} 
} 
}, 


"additionalProperties": false, 
"required": ["tags"] 


} 
根据 以 上 示例 中 的 Schema, ffi] 5-19 中 的 ISON 文档 是 合法 的 。 


例 5-19  ex-8-array-enum.json 


{ 
"tags": ["Java", "REST" ] 


} 
例 5-20 中 的 JSON 文档 则 是 非法 的 ， 因 为 其 tags 数组 中 包含 的 "JIS" 并 不 是 Schema 中 的 
enum 枚 举 值 。 
例 5-20 ex-8-array-enum-invalid.json 


{ 
"tags": ["Java", "REST", "JS"] 

















在 命令 行 中 进行 校 验 后 可 以 看 到 结果 为 非法 : 


json-at-work => validate ex-8-array-enum-invalid.json ex-8-array-enum-schema. json 
Invalid: No enum match for: "JS" 





JSON Schema element: /properties/tags/items/type 
JSON Content path: /tags/2 





5.2.7 WK 


可 以 使 用 JSON Schema 声明 对 象 。 利 用 这 一 点 可 以 校 验 在 应 用 程序 间 交 换 的 对 象 数据 ， 
此 其 是 语义 校 验 的 核心 。 借 助 这 一 功能 ，API 的 提供 者 和 使 用 者 可 以 就 业务 上 一 些 重要 概念 
(如 person 或 order) 的 结构 和 内 容 达 成 共识 。 例 5-21 中 的 Schema 声明 了 speaker 对 象 。 


例 5-21 ex-9-named-object-schema.json 
{ 
"Sschema": "“http://json-schema.org/draft-04/schema#", 
"type": "object", 
"properties": ( 
"speaker": { 
"type": "object", 
"properties": ( 
"FirstName": { 
"type": "string" 








Fs 
"LastName": { 
"type" à "string" 
}, 
"email": { 
"type" $ "string" 
F; 


"postedSlides": { 
"type": "boolean" 
}, 
"rating": { 
"type": "number" 


"tags": { 
"type": "array", 
items": { 
"type": "string" 
} 
} 
}, 
"additionalProperties": false, 
"required": ["firstName", "LastName", "email", 
"postedSlides", "rating", "tags" 
] 
} 
}, 
"additionalProperties": false, 
"required": ["speaker"] 


} 
除了 在 根 节 点 对 象 中 增加 了 一 级 对 象 speaker， 这 一 Schema 与 之 前 示例 中 的 基本 类 似 。 
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根据 该 Schema， 例 5-22 中 的 JSON 文档 是 合法 的 。 


fj 5-22 ex-9-named-object.json 
{ 
"speaker": { 
"firstName": "Larson", 
"lastName": "Richard", 
"email": "Larsonrichard@ecratic.com", 
"postedSlides": true, 
"rating": 4.1, 
"tags": [ 
"JavaScript", "AngularJS", "Yeoman" 
] 
} 
} 





例 5-23 中 的 JSON 文档 则 是 非法 的 ， 因 为 其 speaker 对 象 中 缺失 必需 的 rating 字段 。 
例 5-23 ex-9-named-object-invalid.json 


{ 

"speaker": { 
"firstName": "Larson", 
"lastName": "Richard", 
"email": "Larsonrichard@ecratic.com", 
"postedSlides": true, 
"tags": [ 

"JavaScript", "AngularJS", "Yeoman" 

] 

} 

















j 
在 命令 行 中 进行 校 验 后 ， 可 以 看 到 结果 为 非法 : 


B 





json-at-work => validate ex-9-named-object-invalid.json ex-9-named-object-schema. json 
Invalid: Missing required property: rating 


JSON Schema element: /properties/speaker/required/4 
JSON Content path: /speaker 











至 此 ， 我 们 介绍 了 最 重要 的 一 些 基 础 类 型 ， 接 下 来 将 介绍 一 些 更 复杂 的 Schema, 


5.2.8 模式 属性 


通过 使 用 patternProperties 关键 词 ，JSON Schema 中 的 模式 属性 可 以 基于 正则 表达 式 来 
声明 部 分 重复 的 字段 名 。 例 5-24 定义 了 与 地 址 相关 的 字段 。 








例 5-24  ex-10-pattern-properties-schema.json 
{ 
"$schema": "http://json-schema.org/draft-04/schema#", 
"type": "object", 
"properties": { 
"city": { 
"type": "string" 
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"type": "string" 


"zip": { 
"type": "string" 
"country": { 
"type": "string" 


). 


"patternProperties": 
"^line[1-3]$": { 
"type": "string" 


). 


"additionalProperties": false, 


"required": ["city", "state", "zip", "country", "line1"] 


} 





在 以 上 示例 中 ， 正 则 表达 式 ^Line[1-3]$ 允许 ISON 文档 
line2 和 Line3。 以 下 是 对 该 正则 表达 式 的 一 些 解 释 。 

^ 表 示 字 符 串 开头 。 

line 表示 字符 串 "line", 

[1-3] 表示 1 至 3 之 间 的 一 个 整数 。 

$ 表示 字符 串 结尾 。 


值得 注意 的 是 ， 这 3 个 地 址 字段 中 只 有 Unel 字段 是 必需 的 
根据 该 Schema， 例 5-25 中 的 ISON 文档 是 合法 的 。 


例 5-25 


{ 
"Linei": "555 Main Street", 
"Line2": "#2", 











ex-10-pattern-properties.json 

















"city": "Denver", 
"state": "CO", 
"Zip": "80231", 
"country": "USA" 
j 
例 5-26 中 的 ISON 文档 则 是 非法 的 ， 因 
例 5-26 ex-10-pattern-properties-invalid.json 
{ 


"Linei": "555 Main Street", 
"Linea": "#2", 





"city": "Denver", 
"state": "CO", 
"Zip": "80231", 
"country": "USA" 
} 
在 命令 行 中 进行 校 验 后 可 以 看 到 结果 为 非法 : 


中 





出 现 以 下 地 址 字段 :linel、 





， 其 他 字段 都 是 可 选 的 。 





为 其 中 的 Lines 字段 并 不 在 允许 范围 之 内 。 
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json-at-work => validate ex-10-property-patterns-invalid.json ex-10-property-patterns-schema. json 
Invalid: Additional properties not allowed 


JSON Schema element: /additionalProperties 
JSON Content path: /line4 


5.2.9 正则 表达 式 


JSON Schema 还 可 以 使 用 正则 表达 式 来 限制 字段 值 。 例 5-27 中 的 Schema 限制 了 email 字 
段 的 值 ， 限 定 其 遵守 IETF RFC 2822 中 标准 的 电子 邮件 地 址 格式 。 


例 5-27 ex-11-regex-schema.json 
{ 
"Sschema": "http://json-schema.org/draft-04/schema#", 
"type": "object", 
"properties": { 
"email": { 
"type": "string", 
"pattern": "*[\\w|-].]+@[\\w]+\\.[A-Za-z]{2,4}$" 











"FirstName": { 
"type": "string" 

"LastName": { 
"type": "string" 


IF 
"additionalProperties": false, 
"required": ["email", "firstName", "lastName"] 


在 以 上 示例 中 ， 正 则 表达 式 声 明了 合法 的 电子 邮件 地 址 。 以 下 是 对 该 正则 表达 式 的 一 些 
解释 。 
。 ^ 表 示 字 符 串 开头 。 
。 [\\wl-1.]+ 匹 配 以 下 模式 的 一 对 多 实例 : 

一 [Wl-I.] 匹配 单词 字符 (a-za-20-9_), WIS (-) 或 点 号 C). 
。 @ 表示 字符 “@”。 
。 [\\w]+ 匹配 以 下 模式 的 一 对 多 实例 : 

- [Ww] 匹配 单词 字符 (a-zA-z0-9 ), 
。 \\. 表示 字符 “.”。 
e [A-Za-z]{2,4} 对 2-4 个 以 下 模式 进行 匹配 : 

一 [A-Za-z] 匹配 英文 字符 。 
。 $ 表 示 字 符 串 结尾 。 
JSON Schema 中 的 双 反 斜 杠 AV 用 于 表示 正则 表达 式 中 的 特殊 字符 ， 这 么 做 的 原因 是 : 
JSON 文档 的 核心 语法 已 经 将 单反 斜 杠 用 于 转 义 特殊 字符 (如 \b 代表 退 格 ) ， 因 此 标准 正 
则 表达 式 中 的 单反 斜 杜 (\) 无 法 在 ISON Schema 中 正常 工作 。 
根据 该 Schema， 例 5-28 中 的 ISON 文档 是 合法 的 ， 因 为 email 地址 遵循 了 Schema 中 所 声 
明 的 模式 。 
































= 




















-A 
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例 5-28 ex-ll-regex.json 


"email": "Larsonrichard@ecratic.com", 
"firstName": "Larson", 
"lastName": "Richard" 


} 
fil 5-29 中 的 JSON 文档 则 是 非法 的 ， 因 为 其 email 地 址 缺失 了 .com 后 缀 。 
例 5-29 ex-11-regex-invalid.json 




















{ 
"email": "Larsonrichard@ecratic", 
"firstName": "Larson", 
"LastName": "Richard" 





} 
在 命令 行 中 进行 校 验 后 可 以 看 到 结果 为 非法 : 





json-at-work => validate ex-11-regex-invalid.json ex-11-regex-schema. json 
Invalid: String does not match pattern: A[\wl-]+@[\wl-]+\. [A-Za-z]{2,4}$ 


JSON Schema element: /properties/email/pattern 
JSON Content path: /email 


深入 学 习 正 则 表达 式 

正则 表达 式 有 时 显得 复杂 而 又 令 人 性 步 。 全 面 地 介绍 正则 表达 式 超出 了 本 书 范围 ， 如 需 掌 
担 正 则 表达 式 ， 可 以 参考 以 下 资源 ; 

e Michael Fitzgerald 所 著 的 Introducing Regular Expressions (O'Reilly 出 版 社 ) ; 

* Jan Goyvaerts 和 Steven Levithan 所 著 的 Regular Expression Cookbook, Second Edition ( O'Reilly 
出 版 社 ) ; 

e Jeffrey E. F. Friedl 所 著 的 《精通 正则 表达 式 (第 3 版 )》; 
* Regular Expression 101 网 站 ， 这 是 我 最 喜欢 的 正则 表达 式 网 站 ， 
。 RegExr 网 站 ， 

。 Regular-Expressions.info 网 站 。 


5.2.10 ”依赖 属性 

依赖 属性 在 Schema 中 引入 了 依赖 关系 : 某 个 字段 依赖 其 他 字段 的 存在 。dependencies X 
键 词 会 定义 包含 依赖 关系 的 对 象 ， 例 如 : 只 有 某 个 数组 内 所 有 的 字段 都 出 现 后 ， 才 可 以 使 
用 x 字 段 。 在 例 5-30 中 ， 如 果 JSON 文档 内 出 现 了 favoriteTopics 字段 ， 则 tags 字段 必 
须 同 时 出 现 (HII favoriteTopics 字段 依赖 于 tags 字段 ) 。 


例 5-30  ex-12-dependent-properties-schema.json 
































"$schema": "http://json-schema.org/draft-04/schema£" , 
"type": "object", 
"properties": ( 
"email": ( 
"type": "string", 
"pattern": "*[\\w|-].]+@[\\w]+\\.[A-Za-z]{2,4}$" 


E 
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"FirstName": { 
"type": "string" 


š 


"LastName": { 
"type": "string" 
}, 
"tags": { 
"type": "array", 
"items": { 


"type": "string" 
} 
b 
"favoriteTopic": { 
"type": "string" 

} 
F 
"additionalProperties": false, 
"required": ["email", "firstName", "lastName"], 
"dependencies": { 

"favoriteTopic": ["tags"] 
} 

} 


根据 以 上 示例 中 的 Schema， 例 5-31 中 的 JSON 文档 是 合法 的 ， 因 为 同时 出 现 了 favoriteTopics 
字段 和 tags 数组 。 


例 5-31 ex-12-dependent-properties.json 
{ 








"email": "Larsonrichard@ecratic.com", 
"firstName": "Larson", 
"LastName": "Richard", 
"tags": [ 

"JavaScript", "AngularJS", "Yeoman" 
]， 


"favoriteTopic": "JavaScript" 
} 
例 5-32 中 的 JSON 文档 则 是 非法 的 ， 因 为 出 现 favoriteTopics 字段 时 ，tags 数组 缺失 。 


例 5-32 ex-12-dependent-properties-invalid.json 
{ 








"email": "Larsonrichard@ecratic.com", 
"firstName": "Larson", 

"LastName": "Richard", 
"favoriteTopic": "JavaScript" 





j 
在 命令 行 中 进行 校 验 后 可 以 看 到 结果 为 非法 : 


json-at-work => validate ex-12-dependent-properties-invalid.json ex-12-dependent-properties-schema. json 
Invalid: Dependency failed - key must exist: tags (due to key: favoriteTopic) 


JSON Schema element: /dependencies/favoriteTopic/Q 
JSON Content path: 











5.2.11 内 部 引用 
在 Schema 中 使 用 引用 可 以 重用 定义 / 校 验 规则 。 可 以 将 引用 视 作 Schema 领域 内 DRY 
(Don't Repeat Yourself, AERE) 准则 的 一 个 实现 。 引 用 可 以 是 内 部 的 〈 引 用 当前 


Schema 中 的 内 容 )， 也 可 以 是 外 部 的 (引用 外 部 Schema 中 的 内 容 )。 本 节 将 介绍 内 部 引用 。 
在 例 5-33 中 ， 可 以 看 到 email 字段 的 正则 表达 式 已 经 替换 成 $ref，$ref 字段 的 值 则 是 一 























个 URI， 指 向 email 字段 真正 的 定义 / 校 验 规则 。 


。 # 表示 相关 规则 存在 于 当前 Schema 内 部 。 

e /definitions/ 表示 当前 Schema 中 definitions 对 象 的 路 径 。 注 意 ， 此 处 definitions 
关键 词 表示 使 用 的 是 一 个 引用 。 

e emailPattern 表示 definitions 对 象 中 emailPattern 规则 的 路 径 。 

。 JSON Schema 使 用 JSON 指针 ( 详 见 第 7 章 ) 来 声明 URI (40 s/definitions/emailPattern), 





例 5-33 ex-13-internal-ref-schema.json 


} 


"$schema": "http://json-schema.org/draft-04/schema#", 
"type": "object", 
"properties": ( 
"email": ( 
"$ref": "#/definitions/emailPattern" 
}, 
"firstName": { 
"type": "string" 
"LastName": { 
"type": "string" 


}, 
"additionalProperties": false, 
"required": ["email", "firstName", "lastName"], 
"definitions": { 
"emailPattern": { 
"type": "string", 
"pattern": "*[\\wl-|.]+@[\\w]+\\.[A-Za-z]{2,4}$" 


j 


除了 新 增 的 definitions 对 象 ， 以 上 示例 与 之 前 的 Schema 并 无 多 少 不 同 。 例 5-33 只 是 将 





电子 





Bb 件 地 址 的 相关 规则 挪 到 一 处 公用 的 地 方 ， 使 得 Schema 内 的 多 个 字段 可 以 共享 该 规 


则 而 已 。 
根据 该 Schema， 例 5-34 中 的 ISON 文档 是 合法 的 。 
例 5-34 ex-13-internal-ref.json 


{ 


"email": "Larsonrichard@ecratic.com", 
"firstName": "Larson", 
"LastName": "Richard" 
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例 5-35 中 的 ISON 文档 则 是 非法 的 ， 因 为 其 email 地 址 缺失 了 .con 后 级 。 


fij 5-35  ex-13-internal-ref-invalid.json 





{ 
"email": "Larsonrichard@ecratic", 
"firstName": "Larson", 
"LastName": "Richard" 





j 
在 命令 行 中 进行 校 验 后 可 以 看 到 结果 为 非法 : 





json-at-work => validate ex-13-internal-ref-invalid. json ex-13-internal-ref-schema. json 
Invalid: String does not match pattern: A[\wl-]+@[\wl -]+\. [A-Za-z]{2,4}$ 


JSON Schema element: /properties/email/pattern 
JSON Content path: /email 


5.2.12 ”外 部 引用 


外 部 引用 用 于 声明 位 于 外 部 Schema 文件 中 的 校 验 规则 。 在 这 种 情况 下 ，Schema A 可 以 引 
用 Schema B 中 的 一 些 特定 校 验 规则 。 外 部 引用 使 得 企业 内 的 开发 团队 (或 多 个 开发 团队 
间 ) 可 以 重用 常用 的 Schema。 


例 5-36 展示 了 引用 外 部 Schema 的 演讲 者 数据 Schema, 


例 5-36 ex-14-exernal-ref-schema.json 
{ 
"Sschema": "http://json-schema.org/draft-04/schema#", 
"type": "object", 
"properties": { 
"email": { 
"$ref": 
"http: //Localhost:8081/ex-14-my-common- schema. json#/definitions/emailPattern" 
}, 
"FirstName": { 
"type": "string" 























"LastName": { 
"type": "string" 


IF 
"additionalProperties": false, 
"required": ["email", "firstName", "lastName"] 


) 
与 例 5-33 中 的 Schema 相 比 ， 这 一 Schema 存在 两 个 关键 性 的 区 别 。 


。 该 Schema 移 除 了 definitions 对 象 。 不 用 担心 ， 我 们 很 快 就 会 再 次 看 到 它 。 
。 enail 字段 的 Sref 如 今 指 向 了 外 部 Schema 文件 (ex-14-my-common-schema.json), ， 在 
该 外 部 文件 中 搜索 需要 的 定义 / 校 验 规 则 。 本 章 稍 后 将 介绍 外 部 Schema 的 HTTP 地 址 。 


例 5-37 展示 了 该 外 部 Schema 的 内 容 。 























例 5-37  ex-14-my-common-schema.json 


"$schema": "http://json-schema.org/draft-04/schema#", 
"id": "http://localhost:8081/ex-14-my-common-schema. json", 


"definitions": { 
"emailPattern": { 
"type": "string", 
"pattern": "*[\\wl-|.]+@[\\w]+\\.[A-Za-z]{2,4}$" 
} 
} 


包含 emailPattern 校 验 规则 的 definitions 对 象 如 今 保 存在 该 外 部 Schema 文件 中 。 你 可 


Ab A 
能 会 





有 以 下 困惑 。 





。 引用 到 底 是 如 何 工作 的 ? 

。 JSON Schema 校 验 器 如 何 定位 外 部 Schema? 

以 下 是 上 述 问 题 的 答案 。 

e 在 ex-14-external-ref-schema.json 文件 中 ，S$ref rp s 前 的 URI 前 组 (http://localhost:8081/ 
ex-14-my-common-schema.json) 表示 JSON Schema 处 理 器 应 该 在 外 部 Schema 中 搜索 
emailPattern 定义 。 

。 在 外 部 Schema 文件 ex-14-my-common-schema.json 中 , Schema 根 节 点 中 的 id 字段 (JSON 
Schema 的 关键 词 之 一 ) 声明 此 Schema 内 容 可 由 外 部 文件 引用 。 

。 Sref 中 的 URI Fil id 字段 的 值 必 须 严格 匹配 才能 让 引用 正常 工作 。 

* definitions 对 象 的 工作 方式 与 内 部 引用 相同 。 


根据 该 Schema， 例 5-38 中 的 JSON 文档 是 合法 的 。 值 得 注意 的 是 ， 与 之 前 的 JSON 文档 
相 比 ， 该 JSON 没有 任何 修改 ， 也 不 会 意识 到 外 部 Schema 的 存在 。 


例 5-38  ex-14-external-ref.json 











"email": "Larsonrichard@ecratic.com", 
"firstName": "Larson", 
"lastName": "Richard" 





例 5-39 中 的 JSON 文档 则 是 非法 的 ， 因 为 其 email 地 址 缺失 了 com 后缀。 


例 5-39  ex-14-external-ref-invalid.json 











"email": "Larsonrichard@ecratic", 
"firstName": "Larson", 
"lastName": "Richard" 


使 用 Schema 校 验 这 一 文档 的 方式 有 两 种 : 


。 通过 文件 系统 实现 外 部 引用 ， 
。 通过 Web 实现 外 部 引用 。 
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首先 ， 我们 来 看 一 下 用 validate 工具 在 文件 系统 上 实现 的 外 部 引用 校 验 : 


json-at-work => validate ex-14-external-ref-invalid.json ex-14-external-ref-schema.json 
Invalid: String does not match pattern: A[\wl-]+@[\wl -]+\. [A-Za-z]{2,4}$ 


JSON Schema element: /properties/email/pattern 

JSON Content path: /email 
运行 结果 显示 ex-14-external-ref-invalid.json 这 一 JSON 文档 非法 ， 不 过 该 示例 的 重点 在 于 : 
validate 命令 在 执行 时 既 包 含 了 主 Schema 文件 (ex-14-external-ref-schema.json), ， 也 包含 
了 外 部 引用 的 Schema 文件 (ex-14-my-common-schema.json)。 
接 下 来 ， 我 们 看 一 下 在 Web 上 实现 的 外 部 引用 校 验 。 我 们 将 Schema 文件 以 静态 资源 的 形式 
部 署 到 Web 服务 器 中 ， 从 而 使 得 sref 和 id 中 的 URI (http://ocalhost:808 1/ex-14-my-common- 
schema.json#/definitions/emailPattern) 可 以 正常 工作 。 如 果 尚 未 安装 Node.js 中 的 http-server 
模块 ， 那 么 可 以 参考 A.2.5 节 中 的 内 容 ， 在 机 器 上 安装 并 运行 这 一 模块 。 
在 外 部 Schema 文件 所 在 的 路 径 下 以 8081 端口 运行 http-server， 可 以 看 到 以 下 结果 : 


json-at-work => http-server -p 8081 
Starting up http-server, serving ./ on: http://0.0.0.0:8081 
Hit CTRL-C to stop the server 


























[Wed, 02 Sep 2015 03:44:00 GMT] "GET /ex-14-my-common-schema.json" "undefined" 
[Wed, 02 Sep 2015 03:44:16 GMT] "GET /ex-14-my-common-schema. json" "undefined" 








VR] 


当 在 浏览 器 中 访问 http://localhost:8081/ex-14-my-common-schema.json 时 ， 可 以 看 到 如 
5-5 所 示 的 结果 。 














o | | localhost:8081/ex-14-my 


€ C fi O localhost:8081/ex-14-my-common-schema.json 


{ 
$schema: "http://json-schema.org/draft-04/schemaf", 
id: "http://localhost:8081/ex-14-my-common-schema.json", 
- definitions: ( 
- emailPattern: ( 
type: "string", 
pattern: "^[Ww|-]*6[Ww|-]* S. [A-Za-z] (2,4) $" 




















5-5, 可 通过 Web 访问 的 外 部 Schema 


对 外 部 Schema 开放 Web 访问 后 ， 我 们 执行 校 验 操作 ， 然 后 就 可 以 看 到 文档 的 校 验 结果 为 
非法 : 





json-at-work => validate ex-14-external-ref-invalid.json ex-14-external-ref-schema.json 
Invalid: String does not match pattern: A[\wl-]+@[\wl -]+\. [A-Za-z] (2,4) $ 


JSON Schema element: /properties/email/pattern 
JSON Content path: /email 








5.2.13 ”选择 校 验 规 则 


除了 requires 和 dependencies 关键 词 ， 对 于 供 Schema 处 理 器 使 用 的 校 验 规则 ，JSON 
Schema 还 提供 更 多 细 粒 度 的 机 制 。 以 下 是 一 些 相关 的 关键 词 。 




















oneOf 

有 且 仅 有 一 条 规则 匹配 。 
anyOf 

一 条 或 多 条 规则 匹配 。 
aLLOf 

所 有 规则 均 匹 配 。 
1. oneof 


oneOf 关键 词 在 多 条 校 验 规则 中 强制 进行 排他 选择 (有 且 仅 有 一 条 规则 匹配 )。 在 例 5-40 
的 Schema 中 ，rating 地 耻 的 慎 可 以 小 于 2.0, 或 者 大 于 5.0, 但 不 和 E 同 时 满足 这 两 点 。 


例 5-40 ex-15-one-of-schema.json 
{ 
"$schema": "http://json-schema.org/draft-04/schema#", 
"type": "object", 
"properties": { 
"email": { 
"type" : "string" » 
"pattern": "*[\\w|-].]+@[\\w]+\\.[A-Za-z]{2,4}$" 
"firstName": { 
"type": "string" 
3 
"postedSlides": ( 
"type": "boolean" 








"rating": ( 
"type": "number", 
"oneOf": [ 
{ 
"maximum": 2.0 


E 


{ 
"minimum": 5.0 
} 
] 
} 

}, 
"additionalProperties": false, 
"required": [ "email", "firstName", "LastName", "postedSlides", "rating" ] 


} 


根据 该 Schema, fj 5-41 中 的 ISON 文档 是 合法 的 ， 因 为 rating 字段 的 值 为 4.1， 仅 与 其 
中 一 条 校 验 规则 匹配 («5.0). 
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例 5-41 ex-15-one-of.json 


{ 
"email": "Larsonrichard@ecratic.com", 
"firstName": "Larson", 
"LastName": "Richard", 
"postedSlides": true, 
"rating": 4.1 

} 








例 5-42 中 的 JSON 文档 则 是 非法 的 ， 因 为 其 rating 字段 的 值 1.9 同时 与 两 条 校 验 规则 相 匹 














配 (<2.0 «5.0), 


例 5-42  ex-15-one-of-invalid.json 
{ 
"email": "Larsonrichard@ecratic.com", 
"firstName": "Larson", 
"LastName": "Richard", 
"postedSlides": true, 
"rating": 1.9 








j 
E 命 令 行 中 进行 校 验 后 可 以 看 到 结果 为 非法 : 


BE 


json-at-work => validate ex-15-one-of-invalid.json ex-15-one-of-schema. json 
Invalid: Data is valid against more than one schema from "oneOf": indices 0 and 1 


JSON Schema element: /properties/rating/oneOf 





JSON Content path: /rating 


2. anyOf 
anyOf 关键 词 在 多 条 校 验 规则 中 检测 是 否 出 现 匹 配 。 在 例 5-43 中 ， 除 了 布尔 
字段 还 支持 [Yly]es 和 [NIn]o 字符 串 。 











例 5-43  ex-16-any-of-schema.json 
{ 
"$schema": "http://json-schema.org/draft-04/schema#", 
"type": "object", 
"properties": { 
"email": { 
"type": "string", 
"pattern": "*[\\w|-].]+@[\\w]+\\.[A-Za-z]{2,4}$" 
}, 
"FirstName": { 
"type": "string" 


Fs 
"LastName": { 
"type": "string" 
J 
"postedSlides": { 
"anyOf": [ 
{ 


"type": "boolean" 


’ 


fin 














, postedSlides 
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"type": "string", 
"enum": [ "yes", "Yes", 
} 
] 
}, 
"rating": { 
"type": "number" 
} 
F 
"additionalProperties": false, 
"required": [ "email", "firstName", "lastName", "postedSlides", "rating" ] 


} 
根据 该 Schema， 例 5-44 中 的 JSON 文档 是 合法 的 ， 因 为 postedSlides 字段 的 值 为 "yes"。 


例 5-44 ex-16-any-of.json 
{ 
"email": "larsonrichard@ecratic.com", 
"firstName": "Larson", 
"lastName": "Richard", 
"postedSlides": "yes", 
"rating": 4.1 


} 


例 5-45 中 的 ISON 文档 则 是 非法 的 ， 因 为 其 postedslides 字段 的 值 为 "maybe"， 但 允许 的 
值 中 并 不 包含 "maybe'" 。 


例 5-45  ex-16-any-of-invalid.json 
{ 
"email": "Larsonrichard@ecratic.com", 
"firstName": "Larson", 
"LastName": "Richard", 
"postedSlides": "maybe", 
"rating": 4.1 


no", "No" ] 


























I 











} 
在 命令 行 中 进行 校 验 后 可 以 看 到 结果 为 非法 : 


json-at-work => validate ex-16-any-of-invalid.json ex-16-any-of-schema. json 
Invalid: Data does not match any schemas from "anyOf" 





JSON Schema element: /properties/postedSlides/anyOf 
JSON Content path: /postedSlides 





3. allof 


使 用 allof 关键 词 后 ， 数 据 必须 与 所 有 的 规则 都 匹配 。 在 例 5-46 H, lastname 字段 必须 是 
长 度 小 于 20 的 字符 串 。 


例 5-46 ex-17-all-of-schema.json 
{ 
"$schema": "http://json-schema.org/draft-04/schema#", 
"type" : "object" ; 
"properties": ( 
"email": ( 
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"type": "string", 

"pattern": "*[\\w|-|.]+@[\\w]+\\.[A-Za-z]{2,4}$" 
Fs 
"firstName": { 

"type": "string" 


}, 
"LastName": { 
"allof": [ 
{ "type": "string" }, 
{ "maxLength": 20 } 
] 
}, 


"postedSlides": { 
"type": "boolean" 


Ts 
"rating": ( 
"type": "number", 
"maximum": 5.0 
} 
b 


"additionalProperties": false, 
"required": [ 
"email", 
"firstName", 
"lastName", 
"postedSlides", 
"rating" 
] 
} 


根据 该 Schema, fii] 5-47 中 的 ISON 文档 是 合法 的 ， 因 为 LastName 字段 的 长 度 < 20, 
例 5-47  ex-17-all-of.json 


{ 
"email": "Larsonrichard@ecratic.com", 
"firstName": "Larson", 
"LastName": "Richard", 
"postedSlides": true, 
"rating": 4.1 

} 


例 5-48 中 的 JSON 文档 则 是 非法 的 ， 因 为 其 LastName 字段 的 长 度 超过 了 20 个 字符 。 


例 5-48 ex-17-all-of-invalid.json 
{ 
"email": "Larsonrichard@ecratic.com", 
"firstName": "Larson", 
"LastName": "ThisLastNameIsWayTooLong", 
"postedSlides": true, 
"rating": 4.1 





j 
在 命令 行 中 进行 校 验 后 可 以 看 到 结果 为 非法 : 





json-at-work => validate ex-17-all-of-invalid.json ex-17-all-of-schema.json 
Invalid: String is too long (24 chars), maximum 20 


JSON Schema element: /properties/lastName/allOf/1/maxLength 
JSON Content path: /LastName 








Xt ISON Schema 及 其 语法 进行 了 基本 介绍 后 ， 接 下 来 我 们 探讨 如 何 使 用 JSON Schema 来 
设计 API。 


5.3 如何 使 用 JSON Schema 设计 和 测试 API 


JSON Schema 的 意义 在 于 定义 应 用 程序 和 API 间 数 据 交 换 的 语义 和 结构 。 在 API 设计 领 
域 ， 可 以 将 JSON Schema 理解 为 协议 (接口 ) 的 一 部 分 。 本 节 将 基于 理论 概念 创建 一 个 可 
运行 的 模拟 API， 且 其 他 应 用 程序 和 API 可 以 对 此 模拟 API 进行 测试 与 使 用 。 


5.3.1 应 用 场景 

我 们 将 继续 使 用 之 前 章节 中 的 演讲 者 数据 模型 ， 并 逐步 添加 约束 和 功能 。 以 下 是 从 概念 到 
可 运行 的 模拟 API 所 需要 执行 的 步骤 。 

(1) 对 JSON 文档 进行 建 模 。 

(2) 生 成 JSON Schema, 

(3) 生成 示例 数据 。 

(4) 用 json-server 部 署 模拟 API。 


5.3.2 ”JSON 文 档 建 模 


在 创建 Schema 前 ， 我 们 需要 先 了 解 交 换 的 数据 。 除 了 数据 的 字段 及 格式 外 ， 对 数据 本 身 
的 样子 有 个 良好 的 感性 认 知 也 是 很 重要 的 。 要 想 获 取 良 好 的 感性 认 知 ， 最 大 的 困难 来 自 于 
JSON AD: 手动 创建 ISON 文档 繁琐 且 易 错 。 因 此 ， 应 当 使 用 建 模 工具 来 避免 大 量 的 手 
动 输入 工作 。 在 诸多 优秀 的 工具 中 ， 我 最 中 意 的 是 JSON Editor Online。 有 关 JSON Editor 
Online 的 功能 ， 参 见 1.5.3 节 。 













































































图 5-6 展示 了 JSON Editor Online 中 的 speaker 模型 。 
在 创建 ISON 文档 时 ， 应 当先 使 用 JSON Editor Online 对 数据 进行 建 模 ， 然 后 生成 JSON X 


























档 ， 而 不 是 直接 手动 输入 JSON 文档 。 在 图 5-6 右 侧 区 域 的 ISON 模型 中 ， 点 击 对 象 、 名 
称 一 值 对 或 数组 等 元 素 旁 的 图 标 ， 即 可 在 出 现 的 目录 中 选择 添加 /插入 以 下 新 的 元 素 : 

。 对 象 

。 名 称 一 值 对 

。 数组 
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JSON Editor Online New Open v Save v Settings v Help 





1-6 v object (7) 

2 "about": "Fred Smith is the CTO of Full Ventures, where he ...", Le 

3 "email": “fred. smith@fullventures.com", about : Fred Smith is the CTO of Full Ventures, where he ... 
4 "firstName": "Fred", : " 

5 "lastName": "Smith", < email : fred. smith@fullventures. com 

6 "picture": "http://placehold.it/fsmith-full-ventures-small.png", Virgine ciPred 

+ tags": [ 

8 "Javascript", lastName : Smith 

9 "REST", 

1e "ISON" picture : http: //placehold.it/fsmith-full-ventures-small.png 
11 L 

12 "company": "Full Ventures, Inc." » tags [3] 

—L company : Full Ventures, Inc. 











5-6; jsoneditoronline.com 网 站 中 的 演讲 者 数据 模型 





添加 一 些 字 段 后 ， 可 以 点 击 页 面 中 间 的 左 箭头 按钮 来 生成 JSON 文档 。 接 下 来 就 可 以 对 文 
档 内 容 进 行 运 代 式 的 添加 、 测 试 和 检查 ， 直 到 满意 为 止 。 最 后 ， 通 过 选择 Save 目录 下 的 
Save to Disk 选项 ， 将 JSON 文档 保存 为 本 地 文件 ， 如 例 5-49 所 示 。 


例 5-49 ex-18-speaker.json 
{ 
"about": "Fred Smith is the CTO of Full Ventures, where he ...", 
"email": "fred.smith@fullventures.com", 
"firstName": "Fred", 
"lastName": "Smith", 
"picture": "http: //placehold.it/fsmith-full-ventures-small.png", 
"tags": [ 
"JavaScript", 
"REST", 
"JSON" 
l. 


"company": "Full Ventures, Inc. 


j 


在 继续 深入 前 ， 最 好 人 先 使 用 JSONLint (Web 应 用 程序 或 命令 行 界面 ) 来 校 验 刚 生成 的 JSON 
文档 。 虽 然 ISON Editor Online 所 生成 的 JSON 都 是 合法 的 ， 但 进行 一 下 复查 总 归 不 会 有 错 。 

















5.3.3 生成 JSON Schema 


生成 合法 的 JSON 文档 后 ， 即 可 根据 该 文档 的 结构 与 内 容 使 用 JSONSchema.net 来 生成 相 
应 的 ISON Schema。 再 次 强调 ， 使 用 工具 能 够 节省 大 量 的 手动 输入 工作 。 























AR 
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访问 图 5-7 所 示 网 站 并 将 JSON 文档 粘贴 在 左 侧 输入 框 中 。 











@ © € / Bison schema Generator x \ 
e Q ft D jsonschema.net/#/ A a 
JSONSchema.net Home About Contact Resources Previous Version # Previous Vers 
JSON Schema 
URL http://jsonschema.net Edit View | Sting View’ 
JSON "email": "fred.smithefullventures.com", { 
"firstName": "Fred", 





"lastName": "Smith", 
"picture": "http://placehold.it/fsmith-full- 
ventures-small.png", 
"tags": [ 
"JavaScript", 
"REST", 
"JSON" 


"company": "Full Ventures, Inc." 


Well done! You provided valid JSON. 


Metadata Include metadata keywords 


General — (7 Inciude default values 
Values are taken from JSON. 


Restrict values to enum 











图 5-7; 4 JSONSchema.net 网 站 上 生成 演讲 者 数据 Schema 


使 用 默认 设置 ， 并 进行 以 下 变更 来 生成 Schema。 
* XH] “Use absolute IDs", 

* XH] "Allow additional properties" , 

。 点 击 Generate Schema 按钮 。 

。 将 右 侧 区 域 中 生成 的 Schema 复制 到 粘贴 板 中 。 


将 粘贴 板 中 的 Schema 保存 到 本 地 文件 后 ， 就 可 以 看 到 如 例 5-50 所 示 的 结果 。 


例 5-50 ex-18-speaker-schema-generated.json 


{ 
"Sschema": "http://json-schema.org/draft-04/schema#", 
"id": sf : 
"type": "object", 
"properties": { 
"about": ( 
"id": "about", 
"type": "string" 











"email": ( 
"id": "email", 
"type": "string" 
"FirstName": { 
"id": "firstName", 
"type": "string" 
"LastName": { 
"id": "LastName", 
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"type": "string" 
"picture": ( 

"id": "picture", 

"type": "string" 


"tags": { 
"id": "tags", 
"type": "array", 


"items": [{ 
"id": "0", 
"type": "string" 
Lt 
"Ad": "1", 
"type": "string" 
Lt 
"id" 5.25 
"type": "string" 
}] 
}, 
"company": { 
"id": "company", 


"type": "string" 


IF 

"additionalProperties": false, 

"required": [ 
"about", 
"email", 
"firstName", 
"lastName", 
"picture", 
"tags", 
"company" 

] 

} 


JSONSchema.net 在 生成 基本 的 Schema 方面 是 非常 不 错 的 。 遗 憾 的 是 ， 该 工具 会 添加 一 些 
我 们 不 需要 的 字段 ， 同 时 也 不 支持 enum, pattern 等 高 级 特性 。 使 用 JSONSchema.net 的 意 
义 在 于 它 可 以 完成 80% 的 工作 ， 剩 下 的 工作 则 交 由 你 自行 完善 。 目 前 我 们 还 不 需要 id 字 
段 ， 但 需要 使 用 正则 表达 式 来 校 验 email 字段 (与 之 前 的 示例 一 样 )。 完 成 相关 的 修改 工作 
后 ， 新 的 Schema 如 例 5-51 所 示 。 























tr 





例 5-51 ex-18-speaker-schema-generated-modified.json 


{ 
"Sschema": "http://json-schema.org/draft-04/schema#", 
"type": "object", 
"properties": { 
"about": { 
"type": "string" 
"email": { 
"type": "string", 
"pattern": "*[\\w|-].]+@[\\w]+\\.[A-Za-z]{2,4}$" 
Js 


"firstName": { 
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"type": "string" 


"LastName": { 
"type": "string" 


"picture": { 
"type": "string" 
ps 
ST 
"type": "array", 
"items": [ 


{ 
"type" SEL string " 


] 

js 

"company": { 
"type": "string" 


}, 

"additionalProperties": false, 

"required": [ "about", "email", "firstName", 
"lastName", "picture", "tags", "company" 








] 
) 
5.3.4 校 验 JSON 文 档 
生成 JSON Schema 后 ， 接 下 来 我 们 使 用 JSON Validate 这 一 Web 应 用 程序 来 校 验 ISON 文 
档 。 访 问 图 5-8 所 示 网 站 并 将 ISON 文档 和 Schema 粘贴 到 相应 的 区 域 。 
z — 























9 © © / @.s0n vaicate BS 
€ > Q fi D jsonvalidate.com : 
JSON Validate 
Import About Help 
JSON Content 
8|" a smith-full-ventures-small.png", 




















JSON Schema 
s Hh 
10 HN. (acta-e) (2,4)9" 
1 
20 
is 
x 2t 
References (13f21(3)(4]1(5](6)](7](8] Resuts 
í Vaia 
s 
Learn more about 
Using JSON Schema eo 





图 5-8: € jsonvalidate.com 网 站 上 使 用 JSON Schema 来 校 验 演讲 者 数据 JSON 文档 
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点 击 Validate 按钮 ， 对 于 该 Schema 来 说 ，JSON 文档 的 校 验 结果 应 该 是 合法 的 。 你 可 能 会 
使 用 本 章 中 提 及 的 validate 命令 行 界面 工具 ， 但 Web 应 用 程序 在 可 视 化 方面 做 得 更 好 。 


5.3.5 生成 示例 数据 


至 此 ， 我 们 已 经 拥有 了 一 份 ISON 文档 ， 也 准备 好 了 相应 的 Schema， 但 对 于 创建 测试 API 
来 说 ， 还 需要 更 多 的 数据 。 可 以 使 用 JSON Editor Online 来 生成 测试 数据 ， 但 这 一 方案 存 
在 一 些 丝 漏 : 真实 性 强 的 测试 数据 对 数据 量 和 数据 的 随机 性 有 较 高 要 求 。 即 使 使 用 GUI, 
这 一 目标 也 会 消耗 大 量 人 力 。 

JSON Editor Online 更 适用 于 创建 小 型 的 JSON 文档 ， 以 推进 项 目 设计 ;但 我 们 需要 进行 
API 测试 ， 因 此 需要 能 够 产生 大 量 随 机 ISON 数据 的 方案 。 本 节 会 使 用 JSON 生成 器 来 生 
成 数据 。 访 问 图 5-9 所 示 网 站 后 ， 即 可 看 到 显示 结果 。 















































isActive: ' 
balance: “ 
" 


' 
picture: 'http://placehold.it/32x32', 
, 


age: 
eyeColor: ' 
T 
name: ' 
gender: ' 
company: ' 
email: ' 
phone: “+1 
address: * 


: 
: - 
Created by [35 Follow | 1,760 BE EET TR 1.1k 














5-9; json-generator 网 站 





网 站 左 侧 区 域 的 代码 是 一 个 模板 ， 以 JavaScript 对 象 字面 量 的 形式 表示 ， 用 于 生成 示例 
JSON 数据 。 值 得 注意 的 是 ，JSON 生成 器 可 以 生成 示例 /随机 的 段落 、 数 值 、 名 称 、 全 局 
唯一 标识 符 、 性 别 、 电 子 邮 件 地 址 等 。 另 外 ， 还 可 以 在 模板 顶部 使 用 {{repeat}} 标签 来 批 
量 生成 数据 。 如 需 了 解 有 关 标 签 的 详细 文档 ， 可 点 击 Help 按钮 。 


不 过 ,模板 中 这 么 多 的 默认 设置 已 经 远 远 超过 了 我 们 的 需求 。 例 5-52 对 模板 内 容 进行 了 删 
减 ， 只 留 下 所 需要 的 字段 来 生成 包含 随机 数据 的 3 个 speaker 对 象 。 
例 5-52 ex-18-speaker-template.js 

// http://www.json-generator.com/ 中 所 使 用 的 模板 








[ 
‘{{repeat(3)}}', { 
id: '{{integer()}}', 





126 | $52 


picture: 'http://placehold.it/32x32', 
name: '{{firstName()}}', 
lastName: '{{surname()}}', 
company: '{{company()}}', 
email: '{{email()}}', 
about: '{{lorem(1, "paragraphs")}}' 
} 
] 


点 击 Generate 按钮 后 ， 在 Web 应 用 程序 中 可 以 看 到 如 图 5-10 所 示 的 ISON 文档 (如 果 需 
要 更 多 的 speaker 对 象 ， 将 repeat 标签 中 的 3 改 为 更 大 的 数字 即 可 )。 























Feedback 


1.49 kB| 


T " tpi//placehold i*/22y20" 


i Qr i 
re: 'http://placehold. it/32x32', D trick VUE 
"s 'Coriand 
lastName: ' n d id il lenstrickland@coriander,com" 
company: E bet 5 Quis enim 
email: ' 5 irure sit incididunt do ieee to eaae 
about: ' x labore labore nulla ad 
nostrud irure. Officia 
nisi aliquip. In magna 
veniam. Culpa esse enin Four s Space tab 
sunt ipsum velit nulla 
consectetur magna adipisicing ut.\r\n" 
}, 
{ 
"id" 
to "http://placehold.it/32x32", 














&] 5-10: FB json-generator 生成 演讲 者 数据 JSON 文档 


现在 ， 在 右 侧 区 域 中 点 击 Copy to Clipboard 按钮 ， 将 ISON 内 容 复制 到 文件 中 ， 如 例 5-53 
所 示 。 


例 5-53  ex-18-speakers-generated.json 





[ 

{ 
"id": 5, 
"picture": "http://placehold.it/32x32", 
"name": "Allen", 
"LastName": "Strickland", 
"company": "Coriander", 
"email": "allenstrickland@coriander.com", 
"about": "Quis enim labore ..." 

F3 

{ 
"id": 9, 
"picture": "http://placehold.it/32x32", 
"name": "Merle", 
"LastName": "Prince", 
"company": "Xylar", 
"email": "merleprince@xylar.com", 
"about": "Id voluptate duis ..." 

}， 





JSON Schema | 127 


"id": 8, 

"picture": "http: //placehold.it/32x32", 
"name": "Salazar", 

"LastName": "Ewing", 

"company": "Zentime", 

"email": "salazarewing@zentime.com", 


"about": "Officia qui id ..." 
} 
] 





至 此 ，JSON 文档 的 创建 已 经 接近 完成 。 不 过 ， 为 了 将 该 文件 前 


据 进行 一 些 修改 。 


。 JSON 文档 中 包含 了 一 个 数组 。 将 该 数组 命名 为 speakers， H 





bp 署 为 API， 我 们 需要 对 数 





FH { 和 3} 括 起 来 。 经 过 这 


一 修改 后 ，JSON 文档 的 根 节点 元 素 会 包含 名 为 speakers 的 数组 。 





。 重新 添加 id 字段 ， 以 0 开始。 
最 终 的 JSON 文件 如 例 5-54 所 示 。 











例 5-54 ex-18-speakers-generated-modified.json 


{ 
"speakers": [ 

{ 
"id": 0, 
"picture": "http://placehold.it/32x32", 
"name": "Allen", 
"lastName": "Strickland", 
"company": "Coriander", 
"email": "allenstrickland@coriander.com", 
"about": "Quis enim labore ..." 

}, 

{ 
"id": 1, 
"picture": "http://placehold.it/32x32", 
"name": "Merle", 
"LastName": "Prince", 
"company": "Xylar", 
"email": "merleprince@xylar.com", 
"about": "Id voluptate duis ..." 

}, 

{ 
"id": 25 
"picture": "http://placehold.it/32x32", 
"name": "Salazar", 
"lastName": "Ewing", 
"company": "Zentime", 
"email": "salazarewing@zentime.com", 
"about": "Officia qui id ..." 

} 

] 
} 


ibl 





t 





你 可 能 会 对 上 述 修改 的 用 意 感 到 有 些 困惑 。 这 么 做 的 目的 在 于 : 完成 修改 后 ，json-server 


能 够 以 合适 的 URI 提供 演讲 者 数据 。 
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。 通过 将 数组 封装 到 speakers 中 ， 产 生 的 http://localhost:5000/speakers 路 由 能 够 以 地 址 化 


的 方式 提供 所 有 数据 。 
。 可 以 通 





过 http://localhost:5000/speakers/0 路 由 访问 第 一 个 元 素 。 


我 们 已 经 有 些 超前 了 。 接 下 来 本 节 会 运行 json-server 并 浏览 API. 


5.3.6 
E dr 


sx: 














试 并 提供 反馈 。 如 果 尚 未 安装 json-server 这 








用 json-server 部 署 模拟 API 


Schema 和 测试 数据 后 ， | 数据 部 署 为 API， 以 便 API 的 使 用 者 开始 测 




















相关 指导 步骤 ， 安 装 并 运行 json-server。 





server, 


在 浏览 器 























可 以 看 到 以 下 结果 : 


json-at-work => json-server -p 5000 ./ex-18-speakers-generated-modified.json 
{^_^} Hi! 


Loading database from ./ex-18-speakers-generated-modified.json 
speakers 


You can now go to 


Enter `s` at any time to create a snapshot of the db 


GET /speakers 200 11.750 ms - 1667 
GET /speakers 304 4.027 ms - - 

GET /speakers/@ 200 3.170 ms 

GET /speakers/@ 304 2.556 ms 

GET /speakers/@ 304 1.350 ms 

GET /speakers 304 1.437 ms - 


4 中 访问 http://localhost:5000/speakers， 可 以 看 到 如 图 5-11 所 示 的 结果 。 








— Node.js 模块 ， 那 么 可 以 参考 A.2.5 市 中 的 


在 ex-18-speakers- perierat riodiiied json 文件 所 在 的 路 径 下 ， 以 5000 端口 运行 json- 





Tlocathost:5000/speakers x 


Ct localhost:5000/speakers l mc 





[0] picture. 





id: 0, 
picture: "http://placehold.it/32x32", 








allenstricklandécoriander.com", 

about: "Quis enim labore exercitation elit duis irure sit incididunt dolore esse est. Culpa laboris ex labore labore nulla ad cillum fugiat 
reprehenderit nostrud irure. Officia et cupidatat et pariatur nulla nisi aliquip. In magna et ad eiusmod exercitation veniam. Culpa esse 
enim amet do aliqua reprehenderit sunt ipsum velit nulla reprehenderit. Ad minim consectetur magna adipisicing ut. ' 






id: 1, 
picture: "http://placehold.it/32x32", 





ceéxylar.com", 
laborum laborum esse. Ipsum fugiat ut pariatur adipisicing et cillum. Duis aute cillum adipisicing labore qui 
velit velit nostrud ad. Velit est mollit officia excepteur minim minim occaecat enim qui magna ad ut adipisicing deserunt. Qui officia ex 
aute laboris. Pariatur et anim cillum veniam. Labore eiusmod non velit do eiusmod tempor nostrud do cupidatat. " 


id: 2, 

picture: "http://placehold.it/32x32", 

name: "Salazar", 

lastName: "Ewing", 

company: "Zentime", 

salazarewing@zentime.com", 

: "Officia qui id nostrud non laboris in eiusmod ex et. Aute sunt consequat do labore dolor in et ea excepteur cillum incididunt enim 
Et voluptate qui occaecat eu. Nulla aute esse reprehenderit aliquip officia incididunt excepteur nisi. Culpa ad occaecat ipsum 
deserunt ex dolor ullamco quis. " 











& 5-11: 


json-server 提供 的 演讲 者 数据 模拟 API 
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至 此 ， 在 没有 编写 任何 代码 的 情况 下 ， 我 们 只 通过 部 署 静态 ISON 文件 就 搭建 了 一 个 可 测 
试 的 API。 这 一 方案 的 优雅 之 处 在 于 : 无 论 从 外 观 、 功 能 还 是 使 用 感受 上 来 说 ， 效 果 和 真 
正 的 API 并 无 二 致 。 该 API 所 提供 的 交互 操作 也 和 其 他 API 没有 什么 不 同 。 你 可 以 通过 浏 
bier, CURL 或 者 在 编程 语言 中 发 送 HTTP 请 求 的 方式 来 使 用 该 API。 

不 过 ， 使 用 json-server 会 有 一 个 限制 : 只 能 对 数据 发 送 HTTP GET 请 求 ， 因 为 接口 是 只 
读 的 。 


5.3.7 关于 用 JSON Schema 设计 和 测试 API 的 一 些 思 考 


介绍 完 所 有 示例 后 ， 利 用 强大 的 开源 ISON 工具 来 缩短 API 开发 周期 这 一 点 应 该 会 给 你 留 

下 深刻 的 印象 。 以 下 是 总 结 。 

。 在 最 终 确认 数据 结构 前 ， 使 用 ISON 建 模 工具 进行 设计 。 尽 早 与 相关 负责 人 进行 经 常 性 
沟通 。 

。 手动 编写 JSON 文档 或 Schema 文件 繁琐 上 且 易 错 。 应 当 使 用 工具 来 完成 大 部 分 工作 ， 尽 
量 避 免 人 工 操作 。 

。 及 早 地 、 经 常 性 地 校 验 文档 。 

。 使 用 工具 生成 大 量 的 随机 ISON 数据 ， 而 不 是 自己 手动 创建 。 

。 搭建 模拟 API 是 一 件 比较 简单 的 事情 。 因 为 已 经 有 现成 的 测试 基础 架构 了 ， 所 以 不 要 
试图 从 头 编号。 直接 使 用 现成 的 工具 ， 你 的 时 间 应 该 用 来 做 更 有 价值 的 事情 。 


5.4 使 用 JSON Schema 类 库 进 行 校 验 
本 章 前 面 介绍 了 如 何 使 用 validate 命令 行 工具 以 及 JSON Validate Web 应 用 程序 对 JSON 
文档 进行 Schema 校 验 ， 而 我 们 的 终极 目标 是 在 应 用 程序 内 部 实现 校 验 操作 。 


不 过 ，JSON Schema 并 不 仅仅 适用 于 JavaScript 和 Node.js。 对 于 JSON Schema v4， 大 多 数 
主流 编程 平台 都 提供 了 极 好 的 支持 。 


Ruby on Rails 













































































json-schema gem, 


Java 
json-schema-validator, 


PHP 
jsv4-php, 
Python 


jsonschema, 


Clojure 
直接 使 用 Java 中 的 json-schema-validator 即 可 。 


Node.js 
Node.js 中 存在 不 少 高 质量 的 JSON Schema 处 理 器 。 我 成 功 使 用 过 的 工具 有 以 下 两 个 。 
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。 ajv 是 我 在 Node.js 应 用 程序 中 最 喜欢 使 用 的 类 库 ， 因 为 它 很 简洁 ， 可 以 与 Node.js 
中 流行 的 测试 框架 (Mocha/Chai、Jasmine 和 Karma 等 ) 兼容 。 可 以 在 npm 网 站 和 
GitHub 上 找到 有 关 ajv 的 更 多 信息 。 第 10 章 将 详细 介绍 ajv 的 用 法 。 

e ujs-jsonvalidate 处 理 器 是 本 章 前 面 进行 命令 行 校 验 时 一 直 使 用 的 工具 。 可 以 在 其 
GitHub 页 面 上 找到 更 多 信息 。ujs-jsonvalidate 的 npm 模块 地 址 为 https:/www.npmjs. 


com/package/ujs-jsonvalidate。 


5.5 ”如 何 继续 深入 学 习 JSON Schema 


本 章 描述 了 JSON Schema 的 一 些 基本 知识 ， 但 全 面 的 相关 介绍 已 超出 了 本 章 的 范围 。 除 了 
之 前 提 到 的 json-schema.org 网 站 ， 以 下 是 其 他 一 些 相 关 资 源 。 
* Joe McIntyre 发 起 的 Using JSON Schema 项 目 提供 了 丰富 的 JSON Schema 信息 及 相关 工 
具 ， 其 中 包括 : 
— Using JSON Schema 电子 书 ; 
一 jsonvalidate 应 用 程序 ， 
— ujs-validate npm 模块 。 
。 Michael Droettboom 等 所 著 的 Understanding JSON Schema。 
。 关于 JSON Schema 的 一 个 简介 。 


5.6 ”本 章 回顾 


本 章 介 绍 了 JSON Schema 以 及 它 在 应 用 程序 架构 中 的 作用 ， 然 后 使 用 JSON Schema 及 相 
关 工 具 对 API 进行 了 设计 和 测试 。 

A +e 
5.7 ”内容 预告 


了 解 了 如 何 使 用 JSON Schema 来 结构 化 及 校 验 ISON 文档 后 ， 第 6 章 将 介绍 如 何 搜索 ISON 
文档 。 
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第 6 章 


在 JSON 中 进行 搜索 





通过 使 用 JSON 的 搜索 类 库 和 工具 ， 可 以 简化 JSON 文档 的 搜索 操作 ， 并 快速 访问 需要 
查找 的 字段 。 尤 其 在 Web API 返回 的 大 型 JSON 文档 中 搜索 内 容 时 ，JSON 搜索 可 以 大 显 
身手 。 


本 章 将 介绍 以 下 内 容 : 

。 使 用 ISON 搜索 来 简化 工作 ; 

。 使 用 主流 的 ISON 搜索 类 库 与 工具 ; 

。 编写 单元 测试 ， 在 Web API 返回 的 JSON 文档 中 进行 搜索 。 

在 本 章 示 例 中 ， 我 们 将 使 用 多 种 ISON 搜索 技术 来 搜索 由 本 机 Web API 所 提供 的 ISON 数 
据 。 除 此 之 外 ， 我 们 还 将 创建 单元 测试 ， 从 而 在 测试 中 执行 搜索 操作 并 检查 搜索 结果 。 


6.1 为 什么 要 在 JSON 中 进行 搜索 


设想 以 下 场景 : 某 次 API 调 用 返回 了 几 百 个 〈 或 更 多 ) JSON 对 象 ， 而 你 只 需要 其 中 的 
一 部 分 数据 (名称 - 值 对 )， 或 者 需要 根据 某 个 标准 来 搜索 过 滤 返 回 的 内 容 。 如 果 没 有 
JSON 搜索 操作 ， 你 就 不 得 不 自己 编写 代码 来 解析 JSON 文档 ， 并 在 庞大 的 数据 结构 中 进 
行 遍 历 计 算 。 这 种 偏 底层 的 解决 方案 很 繁琐 ， 同 时 也 意味 着 庞杂 的 处 理 代 码 。 你 的 时 间 应 
该 用 来 做 更 有 价值 的 事情 。 本 章 介 绍 的 ISON 搜索 工具 可 以 有 效 降 低 你 的 工作 量 ， 并 简化 
工作 难度 。 


6.2 JSON 搜索 类 库 和 工具 


(可 在 应 用 程序 内 调用 的 ) 很 多 类 库 和 命令 行 工具 都 可 以 用 于 搜索 JSON 文档 。 以 下 是 本 章 
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将 介绍 的 一 些 广 为 使 用 的 类 库 : 


e JSONPath 
e JSON Pointer 
* jq 


6.2.1 其 他 优秀 工具 

很 多 高 质量 的 类 库 和 命令 行 工 具 都 可 以 用 于 搜索 和 过 滤 JSON 内 容 ， 但 本 书 固 于 篇 幅 无 法 
一 一 介绍 。 以 下 是 其 他 一 些 值得 了 解 的 工具 ， 为 简洁 起 见 ， 本 章 后 面 不 再 对 它们 进行 详细 
讨论 。 















































SpahQL 
SpahQL 有 点 像 是 以 JSON 对 象 为 目标 的 jQuery， 可 以 在 其 GitHub 主页 上 找到 该 类 库 。 
json 


可 以 在 GitHub 和 npm 网 站 上 找到 该 命令 行 工具 。 虽 然 本 章 不 会 使 用 json 的 搜索 功能 ， 
但 依旧 会 用 它 来 优化 JSON 文档 的 显示 。 

jsawk 
jsawk 是 一 个 命令 行 工具 ， 除 搜索 外 ， 它 还 支持 JSON 文档 的 转换 操作 。 


虽然 本 书 不 会 详细 介绍 这 些 工具 的 使 用 ,但 在 你 的 项 目 中 可 能 会 出 现 适用 上 述 工具 的 场 
景 。 可 以 将 这 些 工具 与 JSONPath、JSON Pointer 和 ja 进行 对 比 ， 以 便 确 定 最 佳 选择 。 


6.2.2 选择 工具 的 标准 
因为 存在 大 量 的 类 库 和 工具 ， 所 以 作出 使 用 选择 还 是 比较 困难 的 。 以 下 是 我 的 具体 选择 
标准 。 
关注 度 
该 工具 是 否 广泛 使 用 ? 当 在 网 络 上 进行 相关 搜索 时 ， 能 出 来 多 少 条 搜索 结果 ? 
开发 者 社区 
代码 是 不 是 在 GitHub 上 ? 维护 的 状态 怎么 样 
Ts 
是 否 能 跨 平 台 工 作 ? 标准 或 类 库 接口 是 否 得 到 了 广泛 支持 ? 
易于 入 门 
文档 是 否 齐 全 ? 安装 难度 如 何 ? 接口 设计 是 否 符合 直觉 ?使 用 难度 如 何 ? 
标准 
是 否 存在 相关 标准 (如 IETF、W3C 或 Ecma 等 ) ? 
本 章 将 使 用 上 述 标准 来 评估 ISON 搜索 工具 。 
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6.3 测试 数据 


为 了 演示 搜索 操作 ， 我 们 需要 更 真实 的 测试 数据 和 更 大 、 更 复杂 的 JSON 文档 ， 网 络 上 存 
在 大 量 的 类 似 资 源 。 在 本 章 和 下 一 章 中 ， 我 们 不 再 使 用 之 前 章节 中 的 演讲 者 数据 ， 而 是 从 
公用 APL 中 获取 开放 数据 。 我 们 将 使 用 OpenWeatherMap API 所 提供 的 城市 /天气 数据 。 
可 在 其 官方 网 站 上 查看 具体 的 API 文档。 

本 书 附带 的 chapter-6/data/cities-weather-orig.json 文件 中 包含 了 OpenWeatherMap API 所 
提供 的 美国 加 州 南部 城市 〈 以 经 纬度 划分 的 一 个 矩形 区 域 ) 的 天 气 数据 。 需 要 注意 的 是 ， 
OpenWeatherMap 所 提供 的 天 气 数据 会 发 生 频 繁 的 变化 ， 因 此 本 书 示 例 中 所 截取 的 数据 与 
该 API 所 提供 的 最 新 数据 会 有 一 些 出 入 。 将 天 气 数据 部 署 到 json-server 前 ， 我 们 会 先 对 
其 进行 一 些 人 和 修改。 首先 ， 可 以 在 data/cities-weather-orig.json 文件 中 看 到 天 气 数据 保存 在 一 
个 名 为 list 的 数组 中 。 为 了 明确 并 增加 可 测试 性 ， 我 们 将 该 数组 重 命名 为 cities, FFF 
改动 保存 到 data/cities-weather.json 文件 中 。 另 外 ， 我 们 将 ISON 文档 头 部 的 cod, calctime 
和 cnt 字段 移 到 一 个 新 的 对 象 中 ， 使 之 与 json-server 兼容 ， 因 为 json-server 只 支持 对 象 
或 对 象 数组 。 与 之 前 的 章节 一 样 ， 我 们 会 继续 使 用 json-server 这 一 Node.js 模块 将 城市 天 
气 数据 部 署 为 Web API。 例 6-1 展示 了 修改 后 的 天 气 数据 。 


例 6-1  data/cities-weather.json 
"other": ( 
"cod": 200, 
"calctime": 0.006, 
"cnt": 110 
js 


"cities": [ 




























































































] 
j 


然后 用 以 下 方式 启动 json-server: 


json-server -p 5000 ./cities-weather.json 




















在 浏览 器 中 访问 http://localhost:5000/cities， 应 该 可 以 看 到 如 图 6-1 所 示 的 结果 。 








e e TT localhost:5000/cities x 








€ C fi DQ localhost:5000/cities 





-H 
id: 5386035, 
name: "Rancho Palos Verdes", 
- coord: ( 
lon: -118.387016, 
lat: 33.744461 


temp: 25.56, 
pressure: 1013, 
humidity: 61, 
temp min: 20, 
temp max: 28.89 
) 
dt: 1441486715, 
- wind: ( 
speed: 6.7, 
deg: 290 
Ji 
- clouds: { 
all: 20 
he 
- weather: [ 
id: 801, 
main: "Clouds", 
description: "few clouds", 
icon: "02d" 











图 6-1: 在 浏览 器 中 访问 json-server 提供 的 开放 天 气 数据 
将 需要 测试 的 JSON 数据 部 署 为 模拟 API 后 ， 接 下 来 本 章 将 对 其 进行 单元 测试 。 


6.4 设置 单元 测试 环境 


与 之 前 的 章节 一 样 ， 本 章 中 的 所 有 单元 测试 均 会 在 Node.js 环境 中 通过 Mocha/Chai 来 进 
行 。 在 继续 阅读 前 ， 需 要 确保 已 成 功 设置 测试 环境 。 如 尚未 安装 Node.js， 可 参考 A.2 i 
和 A.2.5 节 中 的 内 容 。 如 需 依照 本 节 的 描述 运行 代码 示例 中 的 项 目 ， 可 使 用 cd 命令 切换 到 
chapter-6/cities-weather-test 目录 ， 并 执行 以 下 命令 来 安装 项 目 依赖 : 


npm install 
如 需 手动 创建 本 节 中 的 Nodejs 项 目 ， 可 参考 本 书 在 GitHub 上 的 相关 指导 步骤 。 
设置 好 测试 环境 后 ， 就 可 以 开始 使 用 JSONPath 和 其 他 的 ISON 搜索 类 库 了 。 
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6.5 比较 JSON 搜 索 类 库 和 工具 


了 解 了 JSON 搜索 的 一 些 基 本 知识 后 ， 本 市 将 比较 以 下 类 库 和 工具 : 


。 JSONPath 
。 JSON Pointer 
* ja 


6.5.1 JSONPath 


JSONPath 是 Stefan Goessner 于 2007 年 开发 的 ， 可 用 于 对 ISON 文档 进行 搜索 和 数据 抽 提 
操作 。 该 类 库 最 开始 是 用 JavaScript 开发 的 ， 但 由 于 其 广 为 流 行 ， 如 今 大 多 数 现代 编程 语 
言 /平台 都 对 其 有 着 良好 的 支持 。 

1. JSONPath 查 询 语法 

JSONPath 的 查询 语法 基于 XPath (一 种 用 于 搜索 XML 文档 的 查询 语言 )。 表 6-1 列举 了 以 
城市 天 气 为 例 的 一 些 JSONPath 查询 语句 。 


表 6-1: JSONPath 查 询 语 句 



















































































JSONPath 查 询 语句 描述 

$.cities 获取 cities 数组 中 的 所 有 元 素 

$.cities.length 获取 cities 数组 中 的 元 素数 目 

$.cities[@::2] 以 每 隔 一 个 元 素 进行 抽取 的 方式 从 cities 数 
组 中 获取 数据 。 有 具体 参考 下 述 有 关 slice() 
的 描述 

$.cities[(Q.length-1)] x $.cities[-1:] 获取 cities 数组 中 的 最 后 一 个 元 素 

$. weather 获取 所 有 的 weather 子 元 素 

$.cities[:3] 获取 cities 数组 的 前 三 个 元 素 

$.cities[:3].name 获取 cities 数组 前 三 个 元 素 的 城市 名 

$.cities[?(Q.main.temp > 84)] 获取 temp [EKF 84 的 所 有 城市 

$.cities[?(@.main.temp >= 84 && @.main.temp <= 85.5)] 获取 temp 值 在 84-85.5 的 所 有 城市 

$.cities[?(@.weather[0].main == 'Clouds')] 获取 天 气 类 型 为 “多 云 ” 的 所 有 城市 

$.cities[?(Q.weather[0].main.match(/Clo/))] 使 用 正则 表达 式 来 获取 天 气 类 型 为 “多 云 
的 所 有 城市 








以 上 查询 语句 示例 使 用 了 JSONPath 的 一 些 关 键 词 和 关键 标识 符 。 


。 $ 表示 ISON 文档 的 根 节 点 对 象 。 

。 .. 表示 拥有 特定 名 称 的 所 有 元 素 和 子 元 素 。 

。 [] 用 于 表示 数组 查询 语句 ， 其 索引 值 则 基于 JavaScript 中 的 slice() 函数 。 对 于 slice() 
PAL, Mozilla 开发 者 网 络 (Mozilla Developer Network, MDN) 提供 了 非常 全 面 的 介绍 。 
以 下 是 对 JSONPath 中 sLice() 的 简单 概览 。 

- 提供 了 选择 数组 中 部 分 内 容 的 功能 。 
































与 JavaScript 中 的 slice() 一 样 ，begin 参数 表示 起 始 索引 值 (第 一 个 值 为 0) Anzi 
— gii 其 默认 值 为 0。 
- 与 JavaScript 中 的 slice() 一样 ，end 参数 表示 结束 索引 值 (索引 值 刚好 为 end 参数 
值 的 元 素 不 包含 在 内 )， 如 忽略 则 默认 为 数组 长 度 值 。 
— step 参数 是 JSONPath ae FAP eae #8 ile HIT A A, BRU 1 
当 step 值 为 1 时 , 返回 的 是 数组 从 begin 到 end 区 域内 的 所 有 元 素 ; 当 step 值 为 2 时 ， 
返回 的 是 数组 从 begin 到 end 区 域内 每 隔 一 个 元 素 抽取 出 的 元 素 集合 。 以 此 类 推 。 
。 4 表示 当前 元 素 。 
。 [?(...)] 用 于 执行 条 件 搜索 。 小 括号 内 可 以 放置 任意 的 JavaScript 表达 式 ， 其 中 包括 条 
件 判 断 表 达 式 (An == 或 >) 和 正则 表达 式 。 


2. JSONPath 在 线 测 试 工 具 
在 没有 编写 任何 代码 的 情况 下 ， 可 以 使 用 一 些 在 线 的 JSONPath 测试 工具 来 实践 JSONPath 
查询 语句 。 在 这 些 工 具 中 ， 我 最 喜欢 Kazuki Hamasaki 提供 的 测试 器 。 只 需 将 data/cities- 


weather.json 文档 (参见 本 章 代码 示例 ) 中 的 内 容 粘 贴 到 左 侧 的 输入 框 中 ， 然 后 再 输入 
JSONPath 查询 语句 ， 即 可 在 页 面 右 侧 区 域 观察 到 搜索 结果 。 如 图 6-2 所 示 。 
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eoo 


JSONPath Online Evaluator x zr 
€ | @ ashphy.com/JSONPathOnlineEvaluator/ Q | Q Search +ravyaeaedgar-@Oas = 
Inputs Evaluation Results 
JSONPath Syntax TU 
$.cities[:3] 


'id' z» "5386035" 

'name' => "Rancho Palos Verdes" 
Example '$.phoneNumbers[*].type' See also JSONPath expressions Sa 
JSON 'lon' => "-118.387016" 
'lat' => "33.744461" 


'temp' => "84.34" 
'pressure' => "1012" 
5g" 





'temp min' => "78.8" 
e max' z» "93" 


r3 
[r] 


"cities": [ 





dt' "1442171078" 
{ wind! 
"id": 5386035, "speed => "4.1" 
“name": : "Banche Palos Verdes", 'deg' => "300 
clouds' ... 
"| ‘all! => "5' 
ee 33.744461 weather" 
'"0* wee 
"main": ( 'id' => "800" 
"temp": 84.34, 


'main' => "Clear" 
'description' => "Sky is Clear" 
'icon' => "92d" 


"pressure": 1012, 


"humidity": 58, 
"temp min": 78.8, 
"temp, max": 93 


'id' => "5392528" 


) ‘name’ => "San Pedro" 
"dt": 1442171078, coord 

"wind": ( 'lon' => "-118.29229" 
"speed": 4.1, "let! "33.735851" 
"deg": 300 











6-2: 用 JSONPath 在 线 工具 搜索 开放 天 气 API 数据 


3. JSONPath 单 元 测试 


fal] 6-2 中 的 单元 测试 练习 了 之 前 表格 中 的 一 些 示 例 JSONPath 查询 语句 。 该 代码 使 用 
jsonpath 这 一 Node.js 模块 ， 对 由 本 机 运行 的 城市 API 所 返回 的 ISON 数据 进行 搜索 。 有 
关 jsonpath 模块 的 详细 信息 ， 可 参考 其 GitHub 主页 。 
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例 6-2  cities-weather-test/test/jsonpath-spec.js 
'use strict'; 

















* 声明 : 城市 天 气 数据 由 0penWeatherMap API 通 过 
Creative Commons Share A _ Like 许可 证 发 布 。 
为 兼容 json-server ， 数 据 经 过 了 一 定 的 修改 。 
此 操作 并 不 意味 着 得 到 了 许可 方 的 背 


此 代码 通过 Creative Commons Share A _ Like 许可 证 发 布 。 
*/ 

















var expect = require('chai').expect; 
var jp = require('jsonpath'); 
var unirest = require('unirest'); 


describe('cities-jsonpath', function() { 
var req; 


beforeEach(function() { 
req = unirest.get('http://localhost:5000/cities') 
.header('Accept', 'application/json'); 
IDE 


it('should return a 200 response', function(done) { 
req.end(function(res) ( 
expect(res.statusCode).to.eql(200); 
expect(res.headers['content-type']).to.eql( 
'application/json; charset-utf-8'); 
done(); 
95 
35 


it('should return all cities', function(done) { 
req.end(function(res) { 
var cities - res.body; 


expect(cities.length).to.eql(110); 
done(); 
}) 
IDE 


it('should return every other city', function(done) { 
req.end(function(res) ( 
var cities - res.body; 
var citiesEveryOther - jp.query(cities, '$[0::2]'); 


expect(citiesEveryOther[1].name).to.eql('Rosarito'); 
expect(citiesEveryOther.length).to.eql(55); 
done(); 
95 
})3 


it('should return the Last city', function(done) { 
req.end(function(res) { 





var cities = res.body; 
var lastCity - jp.query(cities, 'S[(Q.length-1)]'); 


expect(lastCity[0].name).to.eql('Moreno Valley'); 
done(); 
DE 
35 


it('should return the 1st 3 cities', function(done) { 
req.end(function(res) { 
var cities - res.body; 
var citiesFirstThree - jp.query(cities, '$[:3]'); 
var citiesFirstThreeNames = jp.query(cities, '$[:3].name'); 


expect(citiesFirstThree.length).to.eql(3); 

expect(citiesFirstThreeNames.length).to.eql(3); 

expect(citiesFirstThreeNames).to.eql(['Rancho Palos Verdes', 
'San Pedro', 'Rosarito' 


15 


done(); 
3s 
335 


it('should return cities within a temperature range', function(done) { 
req.end(function(res) ( 
var cities - res.body; 
var citiesTempRange - jp.query(cities, 
'S[?(Q.main.temp >= 84 && @.main.temp <= 85.5)]' 
); 


for (var i = 0; i < citiesTempRange.length; i++) { 
expect(citiesTempRange[i].main.temp).to.be.at.least(84); 
expect(citiesTempRange[i].main.temp).to.be.at.most(85.5); 


} 


done(); 
3 
35 


it('should return cities with cloudy weather', function(done) { 
req.end(function(res) ( 
var cities - res.body; 
var citiesWeatherCloudy = jp.query(cities, 
'S[?(Q.weather[0].main == "Clouds")]' 
); 


checkCitiesWeather(citiesWeatherCloudy); 
done(); 
35 
35 


it('should return cities with cloudy weather using regex', function(done) { 
req.end(function(res) { 
var cities - res.body; 
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var citiesWeatherCloudyRegex = jp.query(cities, 
'S[?(Q.weather[0].main.match(/Clo/))]' 
)3 


checkCitiesWeather(citiesWeatherCloudyRegex); 
done(); 
95 
})3 


function checkCitiesWeather(cities) { 
for (var i = 0; i « cities.length; i++) { 
expect(cities[i].weather[0].main).to.eql('Clouds'); 
} 
} 
95 


对 于 以 上 示例 ， 需 要 注意 以 下 几 点 。 


。 测试 代码 在 Mocha 的 beforeEach() 方法 中 配置 unirest 的 URI 和 Accept 头 部 ， 以 避免 
配置 代码 的 重复 。 在 describe 语句 所 定义 的 范围 内 , Mocha 会 在 执行 每 个 测试 用 例 (RE 
it 语句) 前 先 运 行 一 遍 beforeEach() 方法 。 

。 测试 用 例 使 用 expect 断言 风格 ， 并 练习 单个 或 更 多 JSONPath 查询 语句 。 

。 调用 jsonpath 模块 的 工作 机 制 如 下 。 

— jp.query() 语 名 接受 JavaScript 对 象 作为 第 一 个 参数 ,同时 接受 JSONPath 查 询 语句 (以 
字符 串 表 示 ) 作为 第 二 个 参数 ， 然 后 以 JavaScript 对 象 的 形式 同步 地 返回 结果 。 

。 因为 向 json-server 发 送 的 请 求 中 包含 了 cities 这 一 数组 的 字段 名 (URI 中 包含 
cities) ， 所 以 上 述 示例 中 所 有 的 JSONPath 查询 语句 都 忽略 了 开头 的 .cities 部 分 。 

— URI 地 址 是 http://localhost:5000/cities。 
一 使 用 $[:3] (而 不 是 $.cities[:3]) 来 获取 前 3 个 城市 的 数据 。 


可 以 新 开 命令 行 终端 并 执行 以 下 命令 来 运行 上 面 的 单元 测试 程序 : 


cd cities-weather-test 
























































npm test 


运行 后 可 观察 到 以 下 结果 : 


json-at-work => npm test 





> mocha test 


cities-jsonpath 
V should return a 200 response 
v should return all cities 
Vv should return every other city 
V should return the last city 
y should return 1st 3 cities 





v should return cities within a temperature range 
v should return cities with cloudy weather 
V should return cities with cloudy weather using regex 





如 果 在 以 上 示例 的 任意 测试 代码 中 调用 console.log(O) 来 打印 相关 变量 ， 那 么 可 以 看 到 
jsonpath 模块 将 返回 以 名 称 - 值 对 表示 的 合法 ISON 文档 。 

4. 在 其 他 平台 中 使 用 JSONPath 

JSONPath 的 使 用 并 不 局 限于 JavaScript 和 Node.js 环境 。 事实 上 ， 大 多 数 主 流 平台 都 对 
JSONPath 有 着 很 不 错 的 支持 。 这 些 平台 包括 : 


* Ruby on Rails 

















* Python 


* Java 


除 此 之 外 ， 还 存在 很 多 其 他 的 优秀 JSONPath 类 库 ， 但 使 用 前 请 确认 其 遵循 了 JSONPath 
的 语法 (参考 Stefan Goessner 的 相关 文章 ) ， 否 则 就 谈 不 上 是 严格 意义 的 JSONPath。 借 
用 《公主 新 娘 》 中 的 一 句 话 来 说 :“ 你 一 直 在 使 用 那个 词 ， 但 我 觉得 它 并 不 是 你 以 为 的 那 


[EH ” 
leo 
































5. JSONPath 记 分 结果 
根据 本 章 开 头 所 列举 的 评估 标准 ， 表 6-2 显示 了 JSONPath 的 记分 结果 。 
表 6-2: JSONPath 记 分 结果 








关注 度 Y 
开发 社区 Y 
平台 JavaScript, Node.js, Java, Ruby on Rails 
易于 入 门 Y 
标准 N 

















JSONPath 提供 了 丰富 的 搜索 特性 ， 并 且 能 在 大 多 数 主 流 平 台 上 工作 。 其 唯一 缺陷 在 于 
JSONPath 并 不 是 一 项 标准 ， 同 时 也 缺乏 命令 行 界面 的 相关 实现 。 不 过 ， 这 对 于 实际 使 用 
来 说 无 伤 大 雅 。JSONPath 广 为 接 受 且 有 着 较 高 的 社区 使 用 率 ， 同 时 也 提供 了 优秀 的 在 线 
测试 工具 。 对 于 访问 、 搜 索 ISON 文档 并 获取 数据 子 集 来 说 ，JSONPath 可 以 有 效 减 少 代 


码 量 。 


























6.5.2 JSON Pointer 


JSON Pointer 是 用 于 获取 ISON 文档 中 某 个 特定 值 的 一 项 标准 。 关 于 其 细节 ， 可 参考 ISON 
Pointer 的 标准 文档 。 设 计 JSON Pointer 的 主要 目的 在 于 支持 JSON Schema 标准 中 的 Sref 
功能 (在 同一 Schema 中 对 校 验 规则 的 定位 引用 ， 详 见 第 5 章 )。 

1. JSON Pointer 查 询 语法 

思考 以 下 文档 : 
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"cities": [ 


"id": 5386035, 
"name": "Rancho Palos Verdes" 


"id": 5392528, 
"name": "San Pedro" 


"id": 5358705, 
"name": "Huntington Beach" 
} 
] 
} 


K 6-3 描述 了 这 一 文档 中 常用 的 JSON Pointer 查询 语法 。 
表 6-3: JSON Pointer 查 询 
JSON Pointer 查 询 描述 

















fertiges 获取 数组 中 所 有 的 城市 
/cities/0 获取 第 一 个 城市 
/cities/1/name 获取 第 二 个 城市 的 名 称 














JSON Pointer 的 查询 语法 非常 简单 ， 其 工作 机 制 如 下 。 

。 | 表示 路 径 分 隔 符 。 

。 数组 的 索引 值 以 0 开头 。 

可 以 注意 到 ， 在 JSON Pointer 标准 中 ， 当 发 起 查询 操作 时 ， 返 回 的 结果 只 会 包含 数据 值 ， 
而 不 会 包含 相关 的 键 名 。 

2. JSON Pointer 单 元 测试 


例 6-3 中 的 单元 测试 实践 了 之 前 表格 中 的 一 些 示 例 ISON Pointer 查询 语句 。 该 代码 使 
用 json-pointer 这 一 Node.js 模块 对 cities API 所 返回 的 JSON 数据 进行 搜索 。 有 关 json- 
pointer 模块 的 详细 信息 ， 可 参考 其 GitHub 主页 。 





























例 6-3  cities-weather-test/test/json-pointer-spec.js 
bus strict'; 
声明 : 城市 天 气 数据 由 0penWeatherMap API 通 过 
Creative Commons Share A Like 许 可 证 发 布 。 
为 兼容 json-server， 数 据 经 过 了 一 poe 
此 操作 并 不 意味 着 得 到 了 许可 方 的 背 



































此 代码 通过 Creative Commons Share A Like 许 可 证 发 布 。 
* 
/ 


var expect = require('chai').expect; 
var pointer = require('json-pointer'); 
var unirest - require('unirest'); 





describe('cities-json-pointer', function() { 
var req; 


beforeEach(function() { 
req = unirest.get('http://localhost:5000/cities') 
.header('Accept', 'application/json'); 


5; 


it('should return a 200 response', function(done) { 
req.end(function(res) ( 
expect(res.statusCode).to.eq1(200); 
expect(res.headers['content-type']).to.eql( 
'application/json; charset-utf-8'); 
done(); 
IDE 
35 


it('should return the 1st city', function(done) { 
req.end(function(res) { 
var cities - res.body; 
var firstCity - null; 


firstCity - pointer.get(cities, '/0'); 
expect(firstCity.name).to.eql('Rancho Palos Verdes'); 
expect(firstCity.weather[0].main).to.eql('Clear'); 
done(); 
35 
335 


it('should return the name of the 2nd city', function(done) { 
req.end(function(res) ( 
var cities - res.body; 
var secondCityName - null; 


secondCityName - pointer.get(cities, '/1/name'); 
expect(secondCityName).to.eql("San Pedro"); 
done(); 
35 
35 
35 


对 于 以 上 示例 ， 需 要 注意 以 下 几 点 。 


。 测试 用 例 使 用 expect 断言 风格 来 运行 示例 ISON Pointer 查询 语句 。 
。 调用 json-pointer 模块 的 工作 机 制 如 下 。 

— pointer.get() 语句 接受 JavaScript 对 象 作为 第 一 个 参数 ， 同 时 接受 ISON Pointer 查 
询 语句 (以 字符 串 表 示 ) 作为 第 二 个 参数 ， 然 后 以 JavaScript 对 象 的 形式 同步 地 返回 
结果 。 

。 因为 向 json-server 发 送 的 请 求 中 包含 了 cities 这 一 数组 的 字段 名 (URI 中 包含 
cities)， 所 以 上 述 示例 中 的 所 有 ISON Pointer 查询 语句 都 忽略 了 开头 的 .cities 部 分 。 

— URI 地 址 是 http://localhost:5000/cities。 

- 使 用 /6 (而 不 是 /cities/0) 来 获取 第 一 个 城市 的 数据 。 


L 
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可 以 新 开 命令 行 终端 并 执行 以 下 命令 来 运行 上 面 的 单元 测试 程序 : 


cd cities-weather-test 














npm test 


运行 后 可 观察 到 以 下 结果 : 


json-at-work => npm test 





> mocha test 


cities-json-pointer 
/ should return a 200 response 
v should return the 1st city 
v should return the name of the 2nd city 





在 以 上 示例 的 should return the 1st city 测试 用 例 中 ， 如 果 调 用 console.log() 来 打印 
firstCity 变量 ， 那 么 可 以 看 到 json-pointer 模块 将 返回 以 名 称 — 值 对 表示 的 合法 ISON 
文档 。 

3. 在 其 他 平台 中 使 用 JSON Pointer 

除了 Node.js， 大 多 数 主流 平台 都 包含 JSON Pointer 相关 类 库 : 


。 Ruby on Rails; 








* Python; 

* Java, Jackson 现在 支持 JSON Pointer 的 查询 语法 。 作 为 JSR 374 标准 的 一 部 分 (JSON 
处 理 1.1 的 Java API), JavaEE 8 将 对 JSON Pointer 提供 原生 支持 。 

有 些 工具 号 称 实 现 了 JSON Pointer， 但 事实 上 却 并 未 遵循 JSON Pointer 标准 。 因 此 ， 当 评 

fii JSON Pointer 类 库 或 工具 时 ， 请 确保 其 遵循 了 REFC 6901 标准 。 再 次 强调 ， 如 果 某 个 工 

有 具 没有 明确 提 到 RFC 6901， 那 么 该 工具 所 做 的 就 不 是 ISON Pointer 处 理 。 

4. JSON Pointer 记 分 结果 

根据 评估 标准 ， 表 6-4 显示 了 JSON Pointer 的 记分 结果 。 

表 6-4: JSON Pointeri 记 分 结果 



































关注 度 Y 

开发 社区 Y 

平台 JavaScript, Node.js, Java, Ruby on Rails 
易于 入 门 Y 

标准 Y — RFC 6901 





























JSON Pointer 提供 了 有 限 的 搜索 功能 。 每 次 查询 只 返回 ISON 文档 中 某 一 个 字段 的 值 。 设 
tt JSON Pointer 的 主要 目的 是 支持 ISON Schema 中 的 Sref 语法 。 
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6.5.3 jq 


jq 是 一 个 提供 了 命令 行 界面 的 JSON 搜索 工具 ， 其 功能 包括 过 让 ISON 和 截取 数组 。 根 据 
其 GitHub 主页 ，jq 有 点 像 是 JSON 中 的 sed。 不 过 ， 对 ja 的 使 用 并 不 仅 限于 命令 行 ， 通 
过 引入 一 些 不 错 的 类 库 ， 你 可 以 在 自己 喜欢 的 单元 测试 框架 中 使 用 ja 〈 详 见 本 节 中 的 “jq 
单元 测试 ”部 分 ) 。 
1. 整合 cURL 
对 于 Web API, UNIX 社区 中 的 很 多 人 会 在 命令 行 中 使 用 cURL 来 发 起 HTTP 调用 。 除 了 
HTTP, cURL 还 提供 了 多 种 协议 的 数据 通信 功能 。 如 需 安装 CURL, WBS AZ 市 中 的 内 容 。 
首先 ， 我们 在 命令 行 中 使 用 cURL 向 城市 API 发 起 GET 请 求 ， 如 下 所 示 : 

curl -X GET 'http://localhost:5000/cities' 
从 城市 API 获取 ISON 响应 后 ， 我 们 通过 管道 将 响应 内 容 输出 到 jqg， 让 其 对 数据 进行 过 滤 
操作 。 以 下 是 一 个 简单 示例 : 

curl -X GET 'http://localhost:5000/cities' | jq .[0] 
运行 该 命令 后 可 以 看 到 以 下 结果 : 


json-at-work => curl -X GET 'http://localhost:500Q/cities' | jq .[@] 
% Total % Received % Xferd Average Speed Time Time Time Current 






















































































Dload Upload Total Spent Left Speed 
100 57510 10057510 0 9 806k 0 --:--:-- --:--:-- --:--:-- 802k 


: 5386035, 
: "Rancho Palos Verdes", 


if 
: -118.387016, 


H , 
: "Clear", 
: "Sky is Clear", 
: "@2d" 





对 于 以 上 示例 ， 需 要 注意 以 下 两 点 。 

。 cURL 向 OpenWeatherMap API 发 起 HTTP GET 请 求 ， 并 将 JSON 响应 导入 标准 输出 。 

。 ja 从 标准 输入 中 读 取 JSON， 从 这 一 API 数 据 中 选择 第 一 个 城市 ， 并 将 第 一 个 城市 的 
JSON 结果 显示 到 标准 输出 。 
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在 API 开 发 工具 中 ,cURL 是 非常 有 价值 且 强 大 的 。cURL 支持 API 测试 中 所 需 的 所 有 
HTTP 方法 (GET, POST, PUT 和 DELETE)。 我 们 只 是 介绍 了 cURL 的 一 些 皮毛 ， 如 需 学 习 更 
多 有 关 cURL 的 知识 ， 可 参考 其 官方 网 站 。 

2. jq 查 询 语 法 

X 6-5 展示 了 一 些 基 本 的 jq 查询 语句 。 

表 6-5: jq 查 询 语句 






























































jq 查 询 语句 描述 

.cities[0] 获取 第 一 个 城市 。jq 的 数组 过 滤 索 引 值 以 0 开头 

.cities[-1] 获取 最 后 一 个 城市 。 索 引 值 -1 表示 数组 中 的 最 后 一 个 元 素 

.cities[0:3] 获取 前 三 个 城市 ， 其 中 0 为 起 始 索 引 (自身 包含 在 内 ) 3 为 结尾 索 
引 (自身 不 包含 在 内 ) 

.cities[:3] 获取 前 三 个 城市 。 这 一 语句 忽略 了 起 始 索引 ， 是 一 种 快捷 写法 

.cities[] | select (.main.temp >= 获取 满足 以 下 要 求 的 所 有 城市 : 当前 温度 > 80 华氏 度 ， 且 温度 范围 


























80 and (.main.temp min >= 79and 在 79~92 华氏 度 (包括 79 度 和 92 BE) 
.main.temp max <= 92)) 


以 下 命令 展示 了 如 何在 命令 行 中 使 用 3a 查询 来 获取 最 后 一 个 城市 : 


cd chapter-6/data 














jq '.cities[-1]' cities-weather.json 


运行 命令 后 可 以 看 到 以 下 结果 : 


json-at-work => jq '.cities[-1]' cities-weather.json 

i 
: 5374732, 

: "Moreno Valley", 


if 
: -117.230591, 
: 33.937519 


: 1442171075, 


if 


r 3 
: "Sky is Clear", 








接 下 来 ， 我 们 将 介绍 一 个 更 具体 的 示例 。 

3. jq 在 线 测试 工具 一 一 jqPlay 

jaPlay 是 一 个 基于 Web 的 ja 测试 器 ， 提 供 了 对 ISON 数据 进行 ja 查询 的 功能 。 如 需 测试 

jqPlay， 可 以 执行 以 下 步骤 来 获取 由 前 三 个 城市 的 id、name 对 象 所 组 成 的 数组 。 

(1) 访 问 jaPlay 网 站 ， 将 chapter-6/data/cities-weather.json 文件 的 内 容 粘贴 到 网 页 左 侧 的 
JSON 文本 框 区 域 中 。 

(2) 将 以 下 ja 查询 语句 粘贴 到 Filter 文本 输入 框 中 : [.cities[0:3] | .[] | { id, name 3]. 


可 以 看 到 如 图 6-3 所 示 的 结果 。 


Share snippet 


Filter Result Compact Output Null Input Raw Input Raw Output Slurp 


L.cities(0:3] | .0 | { id, name )] s [ t 














id": 5386035, 

JSON name": "Rancho Palos Verdes" 

e. - í 

"id": 5392528, 
me": "San Pedro" 


ime": 0.006, jd 
B í 





"id": 3988392, 
me": "Rosarito" 


"id": 5386035, J 
"name": "Rancho Palos Verdes", 





-118.387016, 
33.744461 


Command Line 


ja '[.cities[0:3] | .[] | { id, name )]* 











6-3: 用 jaPlay 搜索 开放 天 气 API 数据 
以 下 是 对 [.cities[0:3] | .[] | { id, name 3] 查询 语句 的 详细 解释 。 
。 | 符号 将 多 个 过 滤 操 作 串 起 来 ( 链 式 级 联 )。 
e .cities[0:3] 从 城市 数组 中 选择 前 三 个 元 素 所 组 成 的 子 数组 。 
。 .[] 返回 该 子 数组 中 的 所 有 元 素 。 
。 { id, name ) 仅 选 择 元 素 中 的 1d 和 name 字段 。 
- 大 括号 (Cn 表示 创建 一 个 新 的 对 象 。 
— id 和 name 表示 该 新 对 象 只 包含 这 两 个 字段 。 
。 最 外 围 的 中 括号 ([ 和 ]) 将 结果 转换 为 数组 。 
浏览 jqPlay 网 页 的 底部 ， 你 可 以 看 到 一 张 速 查 表 ， 其 中 包含 了 更 多 示例 及 文档 的 链接 ， 如 
图 6-4 所 示 。 
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Cheatsheet 


Click on the icons ( [E] ) in the table below to see examples. 


unchanged input 


.foo, .foo.bar, .foo? value at key 国 
ZU EU2: 30021; SW] array operation B 
U, O array/object construction 国 
length length of a value B 
keys keys in an array B 


View source on GitHub 





feed input into multiple filters 


| pipe output of one filter to the next filter. 


select(foo) input unchanged if foo returns true B 
map(foo) invoke filter foo for each input B 
if-then-else-end conditional a 
(foo) string interpolation B 








6-4; jqPlay 中 的 ja 速 查 表 


4. jq-tutorial 


除了 在 线 测 试 器 ，Node.js 社区 还 提供 了 以 npm 模块 形式 发 布 的 一 个 很 不 错 的 jq 教程 。 可 





以 用 以 下 方式 安装 该 教程 : 


npm install -g jq-tutorial 





B 
> 


命令 行 中 运行 jq-tutorial， 可 以 看 到 以 下 结果 : 


json-at-work => jq-tutorial 
jq-tutorial with one of the following: 


* pick 
objects 


mapping 
filtering 
output 
reduce 

















这 一 命令 能 够 显示 所 有 的 jq 教程 。 可 以 选择 其 中 一 个 教程 : 


jq-tutorial objects 


该 教程 展示 了 如 何在 ja 中 使 用 对 象 。 通 过 阅 
jq 上 的 技能 水 平 。 
5. jq 单 元 测试 














读 所 有 的 学 习 条 目 ， 你 可 以 有 效 增强 自己 在 





Bil 6-4 中 的 单元 测试 实践 了 之 前 的 一 些 示例 ja 查询 语句 。 该 代码 使 用 node-jq 这 一 Node.js 
模块 ， 对 由 本 机 运行 的 cities API 所 返回 的 JSON 数据 进行 了 搜索 。 有 关 node-jq 模块 的 





详细 信息 ， 可 以 参考 其 GitHub 主页 。 


例 6-4  cities-weather-test/test/jq-spec.js 
"Use strict'; 











/* 声明 : 城市 天 气 数据 由 0penWeatherMap API 通 过 
Creative Commons Share A _ Like 许可 证 发 布 。 
为 兼容 json-server ， 数 据 经 过 了 一 定 的 修改 。 

















此 操作 并 不 意味 着 得 到 了 许可 方 的 背书 








此 代码 通过 Creative Commons Share A Like 许 可 证 发 布 。 





*/ 


var 
var 
var 


var _ 


expect = require('chai').expect; 
jq = require('node-jq'); 

unirest = require('unirest'); 

= require('underscore'); 


describe('cities-jq', function() { 
var req; 


beforeEach(function() { 


req = unirest.get('http://localhost:5000/cities') 
.header('Accept', 'application/json'); 


5; 


it('should return a 200 response', function(done) { 


req.end(function(res) { 
expect(res.statusCode).to.eql(200); 
expect(res.headers['content-type']).to.eql( 
'application/json; charset-utf-8'); 
done(); 
5 


5; 


it('should return all cities', function(done) { 


req.end(function(res) { 
var cities - res.body; 


expect(cities.length).to.eql(110); 
done(); 
35 


p); 


it('should return the last city', function(done) { 


req.end(function(res) { 
var cities = res.body; 


jq.run('.[-1]', cities, { 
input: 'json' 

}) 

.then(function(lastCityJson) { // 返回 J]SON 字 符 呈 
var lastCity = JSON.parse(lastCityJson); 
expect(lastCity.name).to.eql('Moreno Valley'); 
done(); 

}) 

.catch(function(error) { 
console.error(error); 
done(error); 

95 

5; 








LT 














ht 
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P, 


it('should return the 1st 3 cities', function(done) { 
req.end(function(res) { 
var cities = res.body; 


jq.run('.[:3]', cities, { 
input: 'json' 
n 
.then(function(citiesFirstThreeJson) { // 返回 JSON 字 符 串 。 
var citiesFirstThree = JSON.parse(citiesFirstThreeJson); 
var citiesFirstThreeNames - getCityNamesOnly( 
citiesFirstThree); 





expect(citiesFirstThree.length).to.eql(3); 
expect(citiesFirstThreeNames.length).to.eql(3); 
expect(citiesFirstThreeNames).to.eql([ 

"Rancho Palos Verdes', 

"San Pedro', 'Rosarito' 


D; 


done(); 

}) 

.catch(function(error) { 
console.error(error); 
done(error); 

35 

35 
35 


function getCityNamesOnly(cities) { 
return _.map(cities, 
function(city) { 
return city.name; 


p); 


it('should return cities within a temperature range', function(done) { 
req.end(function(res) { 
var cities = res.body; 


jq.run( 
'[.[] | select (.main.temp >= 84 and .main.temp <= 85.5)]', 
cities, { 
input: 'json' 
}) 
.then(function(citiesTempRangeJson) { // 返回 ]SON 字 符 串 。 
var citiesTempRange = JSON.parse(citiesTempRangeJson); 








for (var i = 0; i < citiesTempRange.length; i++) { 
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expect(citiesTempRange[i].main.temp).to.be.at.least(84); 
expect(citiesTempRange[i].main.temp).to.be.at.most(85.5); 


} 


done(); 

}) 

.catch(function(error) { 
console.error(error); 
done(error); 

35 

35 
35 


it('should return cities with cloudy weather', function(done) { 
req.end(function(res) { 
var cities - res.body; 


jq.run( 

'[.[] | select(.weather[0].main == "Clouds")]', 

cities, { 
input: 'json' 

}) 

.then(function(citiesWeatherCloudyJson) { // 返回 JSON 字 符 串 。 

var citiesWeatherCloudy = JSON.parse( 

citiesWeatherCloudyJson); 








checkCitiesWeather(citiesWeatherCloudy); 


done(); 

}) 

.catch(function(error) { 
console.error(error); 
done(error); 

35 

35 
35 


it('should return cities with cloudy weather using regex', function(done) { 
req.end(function(res) { 
var cities - res.body; 


jq.run( 

'L.[] | select(.weather[0].main | test("^Clo"; "i"))]', 

cities, { 
input: 'json' 

}) 

.then(function(citiesWeatherCloudyJson) { // 返回 JSON 字 符 串 。 

var citiesWeatherCloudy = JSON.parse( 

citiesWeatherCloudyJson); 
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checkCitiesWeather(citiesWeatherCloudy); 


done(); 

n 

.catch(function(error) { 
console.error(error); 
done(error); 

D 

95 
D 


function checkCitiesWeather(cities) { 
for (var i = 0; i < cities.length; i++) { 
expect(cities[i].weather[0].main).to.eql('Clouds'); 


j 


}); 
对 于 以 上 示例 ， 需 要 注意 以 下 几 点 。 


。 测试 代码 在 Mocha 的 beforeEach() 方法 中 配置 unirest AY URI 和 Accept 头 部 ， 从 而 避 
免 配置 代码 的 重复 。 在 describe 语句 所 定义 的 范围 内 ,Mocha 会 在 执行 每 个 测试 用 例 ( 即 
it 语句 ) 前 先 运行 一 遍 beforeEach() 方法 。 

。 测试 用 例 使 用 expect 断言 风格 来 练习 单个 或 更 多 ja 查询 语句 。 

。 调用 node-jq 模块 的 工作 机 制 如 下 。jq.run() 运行 时 会 进行 以 下 操作 。 

- 接受 jq 查询 语句 〈 以 字符 串 表 示 ) 作为 第 一 个 参数 。 
- 第 二 个 对 象 参数 是 可 选 的 ， 表 明了 输入 的 类 型 。 
4 ( input: 'JSON' } 表 示 一 个 JavaScript 对 象 。 当 unirest 向 json-server 提供 的 
模拟 API 发 起 HTTP 调用 时 ， 返 回 的 结果 为 对 象 ， 因 此 上 述 单元 测试 使 用 了 这 一 
4 { input: 'file' 表示 一 个 JSON 文件 。 该 选项 为 默认 选项 ， 如 果 调 用 jq.run() 
时 不 指定 输入 类 型 ， 则 输入 的 即 为 JSON 文件 。 
4 { input: 'string' } 表示 一 个 JSON 字符 串 。 
— 使 用 ES6 中 的 JavaScript Promise 来 异步 返回 ISON 字符 串 结果 。 在 本 例 中 ， 单 元 测 
试 需要 执行 的 相关 操作 如 下 。 
4 将 测试 代码 包含 在 Promise 的 then 和 catch 结构 中 。 
4 使 用 ISON. parse() 将 结果 解析 为 对 应 的 JavaScript 对 象 结构 。 
— West ESA Promise 的 新 语法 ， 可 访问 MDN 网 站 。 

。 因为 向 json-server 发 送 的 请 求 中 包含 了 cities 这 一 数组 的 字段 名 (URI 中 包含 cities), 
所 以 上 述 示例 中 的 所 有 ja 查询 语句 都 忽略 了 开头 的 .cities 部 分 。 

一 URI 地 址 是 http://localhost:5000/cities。 
— 使 用 $[:3] (而 不 是 $.cities[:3]) 来 获取 前 三 个 城市 的 数据 。 

































































可 以 新 开 命令 行 终端 并 执行 以 下 命令 来 运行 上 面 的 单元 测试 程序 : 


cd cities-weather-test 














npm test 
运行 后 可 观察 到 以 下 结果 : 


json-at-work => npm test 


> mocha test 


cities-jq 
V should return a 200 response 
v should return all cities 
V should return the last city 
V should return the ist 3 cities 
V should return cities within a temperature range 
v should return cities with cloudy weather 
V should return cities with cloudy weather using regex 


| 


如 果 在 以 上 示例 的 任意 测试 代码 中 调用 console.logCO 来 打印 相关 变量 ， 可 以 看 到 node- 3q 
模块 将 返回 以 名 称 - 值 对 表示 的 合法 ISON 文档 。 


6. 在 其 他 平台 中 使 用 jq 
除了 Node.js， 其 他 主流 平台 也 都 包含 了 ja 类 库 。 


Ruby 
可 以 在 RubyGems.org 网 站 上 找到 ruby-jq gem， 也 可 以 参考 其 GitHub 主页 。 


























Java 
Java 中 的 Jackson 类 库 ( 详 见 第 4 章 ) 包含 了 jackson-jq 插件 。 


7. jq 记 分 结果 
根据 评估 标准 ， 表 6-6 显示 了 ja 的 记分 结果 。 


表 6-6: jq 记 分 结果 


T 














关注 度 X 
开发 社区 Y 
平台 CLI—Linux/macOS/Windows, Node.js, Java, Ruby on Rails 
易于 入 门 Y 
标准 N 

















ja 是 一 个 优秀 的 工具 ， 具 体 原因 如 下 。 
。 大 多 数 编程 语言 都 对 Ja 有 着 良好 的 支持 。 
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= 





文档 质量 较 高 。 


提供 丰富 的 搜索 和 过 滤 功 能 。 
可 以 通过 管道 将 查询 结果 输出 到 UNIX 命令 行 界面 工具 (如 sort, grep 和 uniq 等 ) 进 


行 处 理 。 














可 以 在 命令 行 中 很 好 地 与 CURL 这 一 HTTP 客户 端 工具 进行 协同 工作 。 
具有 非常 优秀 的 在 线 测 试 工具 。jqPlay 使 得 你 能 够 在 一 个 简单 的 Web 界面 中 测试 ja d 








询 操作 。 该 工具 能 够 提供 








的 查询 方案 。 





快速 反馈 ， 因 此 可 在 不 编写 任何 代码 的 情况 下 ， 和 迭代 得 到 最 终 








存在 有 用 的 交互 式 教程 〈 详 见 本 节 的 “jq-tutorial” 部 分 )。 

ja 的 唯一 缺陷 在 于 其 初始 学 习 曲 线 较 陡 ， 其 查询 语法 中 的 大 量 选 项 一 开始 可 能 会 显得 过 于 
复杂 ， 让 人 不 知 所 措 。 不 过 ， 花 在 3a 上 的 学 习 时 间 最 终 还 是 物 有 所 值 的 。 

至 此 ， 本 章 介绍 了 ja 的 一 些 基 本 知识 。jq 提供 了 高 质量 的 文档 ， 在 下 列 网 站 中 也 可 找到 




















更 多 详细 信息 : 

。 jq FH; 

。 ja 教程 ; 

。 ja 实例 ; 

e HyperPolyGlot JSON 工具 (ją); 
。 Ubuntu 中 的 jq 手册 页 面 。 


6.6 ”搜索 工具 评估 一 一 总 结 概要 


基于 评估 标准 以 及 总 体 的 可 用 性 ， 我 将 ISON 搜索 类 库 按照 以 下 顺序 排名 : 


(1) jq 
(2) JSONPath 
(3) JSON Pointer 


虽然 JSON Pointer 是 一 项 标准 ， 可 以 用 于 搜索 ISON 文档 ， 但 我 还 是 将 JISONPath 置 于 
JSON Pointer 之 上 上， 原因 如 下 。 

。 JSONPath 的 查询 语法 更 丰富 。 

。 JSONPath 的 查询 语句 可 以 返回 文档 中 的 多 个 元 素 。 

不 过 出 于 以 下 原因 ， 我 最 钟爱 的 ISON 搜索 工具 还 是 ja. 

可 以 在 命令 行 中 工作 (JSONPath 和 JSON Pointer 都 不 提供 此 功能 )。 如 果 需 要 在 自动 化 
运 维 环境 中 处 理 JSON， 则 命令 行 工 具 是 不 可 或 缺 的 。 

具有 在 线 测试 工具 ， 这 一 点 可 以 加 速 开 发 工作 。 





存在 交互 式 教 程 。 
提供 丰富 的 查询 语句 。 
































大 多 数 编程 语言 均 提 供 良 好 的 ja 类 库 支 持 。 














在 JSON 社区 中 的 关注 度 较 高 。 














我 曾 成 功 地 使 用 ja 来 搜索 其 他 Web API (不 是 本 章 中 的 OpenWeatherMap) 提供 的 JSON 
响应 ;该 响应 包含 超过 两 百 万 行 的 数据 ， 而 jq 在 生产 环境 中 完美 地 执行 了 搜索 操作 。jq 
TE ISON 社区 中 拥有 很 高 的 关注 度 ， 只 要 在 网 络 上 搜索 “jq 教程 ， 就 可 以 找到 不 少 优秀 
的 教程 资源 来 帮助 你 更 深入 地 学 习 。 


6.7 本章 回 顾 


本 章 介绍 了 一 些 广 泛 使 用 的 ISON 搜索 类 库 和 工具 ， 并 展示 了 如 何 测试 搜索 结果 。 至 此 ， 和 希望 
你 已 经 接受 了 使 用 ISON 搜索 技术 来 减少 工作 量 的 理念 ， 而 不 是 继续 手工 编写 相关 工具 代码 。 


AA +e 
展示 了 如 何 高 效 搜索 ISON 文档 后 ， 第 7 章 将 介绍 对 ISON 的 转换 操作 。 
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第 7 章 


JSON 转 换 





有 时 应 用 程序 会 从 多 个 API 处 获取 数据 ， 为 了 使 得 数据 格式 与 应 用 架构 相 兼 容 ， 
换 API 的 JSON 响应 。 


可 以 使 用 多 种 JSON 转换 技术 在 JSON 文档 和 其 他 数据 格式 (A HTML 或 XML) iB] E 
行 转 换 ， 或 者 将 ISON 转换 为 新 的 结构 。 很 多 开发 者 已 经 比较 熟悉 其 中 一 些 类 库 (如 
Mustache 和 Handlebars) ; 本 章 将 以 不 落 俗套 的 方式 介绍 这 些 工 具 的 使 用 。 除 此 之 外 ,我 
们 还 将 介绍 JSON-T 这 样 在 技术 社区 不 是 那么 有 名 ,但 在 ISON 社区 却 广 为 使 用 的 类 库 。 


7.1 ”JSON 转换 类 型 

典型 的 转换 类 型 包括 以 下 3 种 。 

将 JSON 转换 为 HTML 
很 多 Web 和 移动 应 用 程序 都 必须 能 够 处 理 API 返回 的 ISON 数据 ， 因 此 这 一 JSON 4% 
换 类 型 是 最 常用 的 。 

对 JSON 的 格式 进行 转换 
有 时 Web API 返回 的 JSON 响应 并 不 是 你 所 需要 的 ， 这 时 你 就 需要 修改 数据 的 格式 以 方 
便 后 续 处 理 。 在 这 种 情况 下 ， 可 以 对 值 进 行 修 改 或 者 移 除 、 添 加 字段 来 更 改 数据 的 结构 。 
有 些 类 库 和 XML 中 的 XSLT (eXtensible Stylesheet Language Transformations， 可 扩展 样式 
表 语 言 转 换 ， 用 于 转换 XML 文档 ) 比较 像 ， 都 通过 使 用 单独 的 模板 来 描述 转换 规则 。 


Ff JSON 转换 为 XML 
基于 SOAP/XML 的 Web Service 并 未 销 亡 ， 因 此 有 时 需要 读 取 XML 并 将 其 转换 成 
JSON， 从 而 与 企业 中 基于 REST 和 JSON 的 新 应 用 程序 保持 兼容 。 相 反 ， 应 用 程序 也 
可 能 需要 向 基于 SOAP/XML 的 Web Service 发 送 XML 数据 。 在 这 种 情况 下 ， 将 JSON 
转换 为 XML 是 不 可 或 缺 的 。 
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本 章 将 介绍 以 下 操作 : 

* 将 JSON 转换 为 HTML; 

。 将 某 个 ISON 文档 转换 为 新 的 JSON 结构 ， 

。 在 XML 和 JSON 之 间 进 行 相互 转换 ， 

。 使 用 JSON 转换 类 库 ， 

。 编写 单元 测试 来 转换 Web API 返回 的 JSON 文档 。 


7.2 选择 JSON 转 换 类 库 的 标准 


与 JSON 中 的 搜索 一 样 ， 每 种 转换 操作 都 有 多 个 类 库 工 具 可 用 ， 因 此 作出 选择 还 是 比较 困 
难 的。 本 章 将 使 用 与 第 6 章 相同 的 评估 标准 。 









































关注 度 
该 工具 是 否 广 泛 使 用 ? 当 在 网 络 上 进行 相关 搜索 时 ， 能 出 来 多 少 条 搜索 结果 ? 
开发 者 社区 
代码 是 不 是 在 GitHub 上 ? 维护 的 状态 怎么 样 ? 
平台 
是 否 能 跨 平 台 工作 ? 标准 或 类 库 接口 是 否 得 到 了 广泛 支持 ? 
易于 入 门 


文档 是 否 齐全 ? 安装 难度 如 何 ? 接口 设计 是 否 符合 直觉 ? 使 用 难度 如 何 ? 需要 编写 多 少 
代码 ? 

标准 
是 否 存在 相关 标准 (如 IETF、W3C 或 Ecma 等 ) ? 


7.3 测试 输入 数据 
我 们 将 使 用 与 第 6 章 相同 的 OpenWeatherMap API 数据 作为 示例 。 原 始 的 OpenWeatherMap 
API 数据 存放 于 chapter-7/ data/cities-weather.json 文件 中 。 出 于 简洁 的 目的 ， 例 7-1 提供 了 
该 数据 的 缩减 版 。 
例 7-1  data/cities-weather-short.json 

{ 


"cities": [ 



































"id": 5386035, 
"name": "Rancho Palos Verdes", 
"coord": { 
"Lon": -118.387016, 
"Lat": 33.744461 
Jo 
"main": { 
"temp": 84.34, 
"pressure": 1012, 
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"humidity": 58, 
"temp min": 78.8, 
"temp max": 93 

}, 

"dt": 1442171078, 

wind": { 


"clouds": { 
"all": 5 
}, 
"weather": [ 
{ 
"id": 800, 
"main": "Clear", 
"description": "Sky is Clear", 
"icon": "02d" 


"id": 5392528, 
"name": "San Pedro", 
"coord": { 

"lon": -118.29229, 
"lat": 33.735851 


main": { 
"temp": 84.02, 
"pressure": 1012, 
"humidity": 58, 
"temp min": 78.8, 
"temp max": 91 

}, 

"dt": 1442171080, 

"wind": { 

"speed": 4.1, 

"deg": 300 


"clouds": { 
"all": 5 
}, 
"weather": [ 
{ 
"id": 800, 
"main": "Clear", 
"description": "Sky is Clear", 
"icon": "02d" 


"id": 3988392, 
"name": "Rosarito", 





AR 


第 7 章 


"coord": { 
"lon": -117.033333, 
"lat": 32.333328 
} 
"main": { 
"temp": 82.47, 
"pressure": 1012, 
"humidity": 61, 
"temp_min": 78.8, 
"temp_max": 86 
} 
"dt": 1442170905, 
"wind": { 
"speed": 4.6, 
"deg": 240 
"clouds": { 
"all": 32 
f 


"weather": [ 


"id": 802, 

"main": "Clouds", 

"description": "scattered clouds", 
"icon": "03d" 


首先 ， 我 们 来 看 一 下 将 JSON 转换 为 HTML 的 操作 。 


7.4 将 JSON 转 换 为 HTML 

大 多 数 开发 者 应 该 已 经 很 熟悉 如 何 将 API 响应 中 的 ISON 转换 为 HTML。 对 于 这 一 转换 ， 
本 市 将 介绍 以 下 类 库 : 

。 Mustache 

。 Handlebars 


7.4.44 目标 HTML 文 档 
我 们 将 简化 7.3 节 中 的 城市 数据 ， 并 最 终 显示 为 如 例 7-2 所 示 的 HTML 表格 。 


例 7-2  data/weather.html 


<!DOCTYPE htmL> 
<html> 


<head> 
<meta charset="UTF-8" /> 
<title>OpenWeather - California Cities</title> 
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«link rel="stylesheet" href="weather.css"> 
</head> 


<body> 
<h1>OpenWeather - California Cities«/hi» 
«table class="weatherTable"> 
<thead> 
<tr> 
«th»City«/th» 
«th»ID«/th» 
«th»Current Temp«/th» 
</tr> 
</thead> 
<tr> 
<td>Santa Rosa</td> 
<td>5201</td> 
<td>75</td> 
</tr> 
</table> 
</body> 
</html> 


在 将 示例 ISON 输入 数据 转换 为 目标 HTML 文档 的 过 程 中 ， 我 们 将 比较 每 个 类 库 的 相关 操作 。 





7.4.2 Mustache 


Mustache 使 用 声明 式 (无 须 编写 逻辑 代码 ) 模板 来 转换 数据 格式 。 在 本 例 中 ， 我 们 会 使 用 
Mustache 将 JSON 数据 转换 为 HTML 文档 。 因 为 使 用 的 模板 只 包含 一 些 简 单 的 标签 ， 没 
有 if/then/else 语句 或 循环 结构 ， 所 以 Mustache 团队 使 用 了 无 逻辑 一 词 来 描述 其 类 库 。 根 
据说 明文 档 ，Mustache 可 以 解析 模板 文件 中 的 标签 ， 解 析 所 用 的 值 则 来 自 应 用 程序 的 hash 
或 对 象 。 无 论 使 用 的 是 Mustache 还 是 Handlebars (Handlebars 中 重新 引入 了 一 些 条 件 逻 
辑 )， 使 用 模板 的 优势 在 于 : 此 方案 从 应 用 程序 代码 中 抽取 转换 信息 ， 并 将 其 保存 在 外 部 
文件 中 ， 从 而 实现 了 关注 点 分 离 。 在 不 修改 应 用 程序 代码 的 情况 下 ， 外 部 模板 使 得 你 可 以 
轻松 地 添加 /删除 数据 格式 ， 或 者 轻而易举 地 改变 数据 格式 化 方法 。 


如 需 了 解 更 多 信息 ， 可 参考 以 下 网 站 : 

。 Mustache 官方 网 站 ; 

e Mustache 的 GitHub 主页 ; 

。 Mustache 5 的 说 明文 档 。 

1. Mustache 模 板 语法 

例 7-3 中 的 Mustache 模板 可 将 OpenWeatherMap 的 JSON 数据 转换 为 HTML, 












































例 7-3 templates/transform-html.mustache 
<!DOCTYPE htmL> 
<htmL> 


<head> 
«meta charset-"UTF-8" /> 
«title»OpenWeather - California Cities</title> 
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«link rel="stylesheet" href="weather.css"> 
</head> 
<body> 
<h1>OpenWeather - California Cities«/hi» 
«table class="weatherTable"> 
<thead> 
<tr> 
<th>City</th> 
<th>ID</th> 
<th>Current Temp</th> 
<th>Low Temp</th> 
<th>High Temp</th> 
<th>Humidity</th> 
<th>Wind Speed</th> 
<th>Summary</th> 
<th>Description</th> 
</tr> 
</thead> 
{{#cities}} 
<tr> 
<td>{{name}}</td> 
<td>{{id}}</td> 
{{#main}} 
<td>{{temp}}</td> 
<td>{{temp_min}}</td> 
<td>{{temp_max}}</td> 
<td>{{humidity}}</td> 
{{/main}} 
<td>{{wind. speed} }</td> 
{{#weather .0}} 
<td>{{main}}</td> 
<td>{{description}}</td> 
{{/weather .0}} 
</tr> 
{{/cities}} 
</table> 
</body> 


</html> 
该 模板 的 工作 机 制 如 下 。 


。 模板 基于 HTML 文档 ，Mustache 则 会 使 用 cities 数组 中 的 数据 来 解析 每 个 标签 。 

。 标签 可 表示 单个 字段 ， 如 {{temp}}。 

。 区 块 由 起 始 标 签 (如 {{#cities}}) 和 结束 标签 (如 {{/cities}}) 围 起 来 。 
一 一 个 区 块 对 应 一 个 数组 (A cities) 或 一 个 对 象 ( 如 main)。 

一 个 区 块 为 其 内 部 的 标签 定义 了 上 下 文 。 如 {{main}} 区 块 内 部 的 {{temp}} 标签 即 可 

表示 为 {{main.temp}}, X JSON 输入 文档 中 的 main.temp 部 分 。 

。 在 标签 中 访问 字段 名 时 ， 可 以 使 用 数组 索引 。 例 如 ，{{#weather .90}} 表示 输入 JSON X 
档 中 的 weather[0] 部 分 。 


接 下 来 我 们 将 在 单元 测试 中 使 用 城市 数据 来 泻 染 模板 。 
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2. Mustache 单 元 测试 

与 之 前 的 章节 一 样 ， 本 章 中 的 所 有 单元 测试 均 通过 Mocha/Chai 来 运行 。 在 继续 阅读 前 ， 
确保 已 成 功 设置 测试 环境 。 如 尚未 安装 Node.js， 可 参考 A2 节 和 A.2.5 节 中 的 内 容 。 如 
需 依 照 本 节 的 描述 运行 代码 示例 中 的 项 目 ， 可 使 用 cd 命令 切换 到 chapter-7/cities-weather- 
transform-test 目录 ， 并 执行 以 下 命令 来 安装 项 目 依赖 ; 


npm install 
如 需 手动 创建 本 节 中 的 Node.js 项 目 ， 可 参考 本 书 在 GitHub 上 的 相关 指导 步骤 。 
例 7-4 中 使 用 了 以 下 Node.js 模块 。 


Mustache 
可 以 在 https://www.npmjs.com/package/mustache 中 找到 该 模块 ， 其 GitHub 主页 为 
https://github.com/janl/mustache.js。 























jsonfile 


我 们 将 使 用 该 模块 从 文件 中 读 取 OpenWeatherMap 的 JSON 数据 ， 并 对 数据 进行 解析 。 
可 以 在 https://www.npmjs.com/package/jsonfile 中 找到 该 模块 ， 其 GitHub 主页 为 https:// 
github.com/jprichardson/node-jsonfile。 


例 7-4 中 的 单元 测试 展示 了 实际 应 用 中 的 Mustache 转换 操作 。 


例 7-4 cities-weather-transform-test/test/mustache-spec.js 
"Use strict'; 























* 声明 : 城市 天 气 数据 由 0penWeatherMap API 通 过 
Creative Commons Share A Like 许 可 证 发 布 。 
为 兼容 json-server， 数 据 经 过 了 一 o m 
此 操作 并 不 意味 着 得 到 了 许可 方 的 背 


此 代码 通过 Creative Commons Share A Like 许 可 证 发 布 。 


























*/ 


var expect = require('chai').expect; 
var jsonfile = require('jsonfile'); 
var fs = require('fs'); 

var mustache = require('mustache'); 


describe('cities-mustache', function() { 
var jsonCitiesFileName - null; 
var htmlTemplateFileName - null; 


beforeEach(function() { 
var baseDir =  dirname + '/../..'; 


jsonCitiesFileName = baseDir + '/data/cities-weather-short.json'; 
htmlTemplateFileName = baseDir + 
' [templates/transform-html.mustache'; 


D; 





it('should transform cities JSON data to HTML', function(done) { 
jsonfile.readFile(jsonCitiesFileName, function(readJsonFileError, 
jsonObj) { 
if (!readJsonFileError) { 
fs.readFile(htmlTemplateFileName, 'utf8', function( 
readTemplateFileError, templateFileData) { 
if (!readTemplateFileError) { 
var template - templateFileData.toString(); 
var html = mustache.render(template, json0bj); 


console. log('\n\n\nHTML Output:\n' + html); 
done(); 
} else { 
done(readTemplateFileError); 
} 
95 
} else { 
done(readJsonFileError); 


} 
355 
5; 
p; 


以 上 代码 的 工作 机 制 如 下 。 


e beforeEach() 方法 会 在 每 个 单元 测试 用 例 执 行 前 先 运行 一 遍 。 在 本 例 中 ， 该 方法 构造 了 
输入 的 ISON 文件 和 Mustache 模板 的 文件 名 。 

e JE 'should transform cities JSON data to HTML' 这 一 单元 测试 用 例 中 : 
一 jsonfile.readFile() 读 取 输 入 的 JSON 文件, 并 将 其 解析 为 JavaScript 对 象 (json0bj)，; 
一 fs.readFile() 读 取 Mustache 模板 文件 ， 并 将 其 保存 到 一 个 JavaScript 对 象 中 ， 
- 然后 将 Mustache 模板 转换 为 字符 串 ， 
一 mustache.render() 使 用 之 前 读 取 的 json0bj 所 提供 的 值 将 Mustache 模板 泻 染 为 

HTML 文档 。 


了 单元 测试 前 ， 打 开 终 端 并 在 命令 行 中 以 5000 端口 运行 json-server 


cd chapter-7/data 








ini 
EN 


json-server -p 5000 ./cities-weather-short. json 


后 新 开 命令 4 ， 执 行 以 下 命令 来 运行 上 面 的 单元 测试 : 


cd chapter-7/cities-weather-transform-test 














npm test 
我 们 可 以 看 到 与 目标 HTML 文档 相似 的 HTML 内 容 。 


3. Mustache 在 线 测试 器 
Architect 模板 编辑 器 是 一 个 非常 优秀 的 在 线 测试 工具 ， 可 以 有 效 简化 测试 、 开 发 Mustache 
模板 的 工作 。 当 修改 模板 时 ， 该 工具 可 以 实时 显示 泻 染 结果 ， 因 此 是 一 个 非常 不 错 的 选 
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择 。 像 这 样 的 所 见 即 所 得 (WYSIWYG，What-You-See-Is-What-You-Get) 工具 可 以 有 效 加 
速 开发 与 调试 工作 。 

打开 Architect 在 线 工 具 ， 在 Engine 下 拉 菜 单 中 选择 Mustache.js， 然 后 将 Mustache 模板 和 
输入 的 JSON 粘贴 到 相应 的 输入 框 中 。 可 以 看 到 如 图 7-1 所 示 的 结果 。 























e o HH Architect - Javascript Tem: x 





G Q fi |O rowno.github.io/architect/ 





< 
= 
= bh 3 









Engine: | Mustache.js $ || C Reset |» EE 0.8.1 » E 2.0KB » github » download 
Template e 
13- <tr> Et 
14 «th» ID«/th» 2- 
15 «th»Citye/th» 3 
16 «th»Current Temp</th> 4 Palos; Nerd 
17 <th>Low Temp</th> S 
18 <th>High Temp</th> 6 : -118.387816, 
19 <th>Humi dity</th> 7 : 33.744461 
20 «th»Wind Speed</th> 8 
n «th» Sumary«/th» e: 
22 <th>Description</th> x 
23 </tr> E 
24 /thead> Hs 
on ette m 
27 <td>{{id}}</td> a 
Result 
12- <thead> 
13- <tr> 
14 <th>ID</th> 
15 <th>City</th> 
16 <th>Current Temp</th> 
i «th»Low Temp</th> 
18 «th»High Temp</th> 
19 <th>Humidity</th> 
20 «th»Wind Speed</th> 
21 «th»Sumary«/th» 
22 <th>Description</th> 





g 3 & A @ © Copyright © 2012 Roland Warmerdam Released under the MIT license 


7-1; Architect; 使 用 Mustache 将 JSON 转换 为 HTML 




















由 于 Architect 还 支持 其 他 的 一 些 模 板 引 擎 (如 下 一 节 将 提 到 的 Handlebars)， 因 此 这 一 工 

具 成 为 了 我 最 喜欢 使 用 的 在 线 模板 编辑 器 。 

不 过 切记 ， 这 一 Web 应 用 程序 是 可 以 公开 访问 的 。 

。 粘贴 到 该 应 用 程序 的 所 有 数据 对 于 其 他 人 来 说 都 是 可 见 的 。 因 此 ， 不 要 在 此 工具 中 使 用 
敏感 信息 (个 人 隐私 、 财 产 信息 等 )。 

。 数据 量 过 大 会 影响 浏览 器 的 运行 。 我 曾经 最 多 使 用 过 10 000 FTA ISON 数据 ， 但 继续 
增加 数据 后 应 用 程序 就 开始 变 得 卡 顿 了 。 

4. 在 命令 行 中 使 用 Mustache 

还 可 以 直接 在 命令 行 中 运行 Mustache。 如 果 已 经 安装 了 Nodejs， 则 可 在 全 局 安装 Mustache 

模块 后 ， 在 本 书 示例 代码 路 径 下 用 命令 行 来 运行 该 模块 : 


npm install -g mustache 























cd chapter-7 


mustache ./data/cities-weather-short.json \ 
./templates/transform-html.mustache > output.html 





5. 在 其 他 平台 上 使 用 Mustache 
Deko oi Mustache 网 站 就 可 以 看 到 ，Mustache 有 着 很 好 的 跨 平台 支持 。 支 持 的 平台 包括 : 


。 Node.js 





e Ruby on Rails 
。 Java 


6. Mustache 记 分 结果 
基于 本 章 开 头 的 评估 标准 ， 表 7-1 展示 了 Mustache 的 记分 结果 。 
表 7-1: Mustache 记 分 结果 








关注 度 Y 
开发 社区 Y 
平台 JavaScript, Node.js, Java, Ruby on Rails 
易于 入 门 Y 
标准 N 

















AIM ZZ, Mustache 是 一 个 强大 、 灵 活 且 广 为 使 用 的 模板 引擎。 虽然 不 是 标准 ， 但 
Mustache 自身 提供 了 非常 可 靠 的 说 明文 档 。 


接 下 来 我 们 将 介绍 Handlebars, 








7.4.3 Handlebars 


Handlebars 是 Mustache 的 一 个 扩展 ， 同 样 使 用 了 hash 或 对 象 中 的 值 来 解析 模板 文件 中 的 标 
签 。Handlebars 与 Mustache 高 度 兼 容 ，Mustache 的 模板 文件 一 般 也 能 在 Handlebars 的 引擎 
中 正常 工作 。 由 于 HTML 转换 操作 非常 简单 ， 因 此 我 们 不 会 看 到 Mustache 和 Handlebars 之 
间 有 什么 区 别 。 与 Mustache 相 比 ，Handlebars 中 添加 了 一 些 特 性 来 增强 转换 操作 ，7.5 节 将 
对 此 进行 详细 介绍 。 如 需 了 解 更 多 有 关 Handlebars 的 信息 ， 可 参考 以 下 资源 : 
e Handlebars 官方 网 站 (可 点 击 Learn More 按钮 获取 更 多 细节 信息 ) ; 
。 Handlebars 的 GitHub 主页 。 
1. Handlebars 与 Mustache 间 的 差别 
通过 提供 额外 的 功能 ，Handlebars 扩展 了 Mustache。 这 些 额 外 功能 如 下 。 
Ae ie 

Handlebars 提供 了 if 和 unless ARAA DEA., 7.5 节 将 介绍 如 何 使 用 unless, 
辅助 语句 

Handlebars 人 允许 开发 者 通过 注册 自 定 义 辅助 语句 的 方式 来 扩展 Handlebars。 每 个 自 定义 
辅助 语句 都 能 提供 一 个 额外 的 可 用 于 模板 的 指令 。 比 如 ， 可 以 将 speaker 的 firstName 
和 LastName 元 素 组 合成 新 的 {{fullName}} 辅助 语句 。 辅 助 语句 非常 强大 ， 但 本 书 不 再 
对 其 进行 深入 介绍 。 如 需 了 解 更 多 有 关 Handlebars 辅助 语句 的 信息 ， 可 以 参考 其 官网 介 
绍 页 面 ， 也 可 以 阅读 Jasko Koyn 撰写 的 文章 “Custom Helpers Handlebars.js Tutorial”。 


Handlebars 的 GitHub 页 面 对 Handlebars 和 Mustache 之 间 的 差别 进行 了 全 面 说 明 。 
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2. Handlebars 模 板 语法 
我 们 使 用 例 7-5 中 的 Handlebars 模板 将 输入 的 JSON 转换 为 HTML 文档 。 


例 7-5 templates/transform-html.hbs 
<!DOCTYPE htmL> 
<html> 


<head> 
<meta charset="UTF-8" /> 
«title»OpenWeather - California Cities</title> 
«link rel="stylesheet" href="weather.css"> 
</head> 
<body> 
<h1>OpenWeather - California Cities«/hi» 
<table class="weatherTable"> 
<thead> 
<tr> 
«th»ID«/th» 
<th>City</th> 
<th>Current Temp</th> 
<th>Low Temp</th> 
«th»High Temp</th> 
<th>Humidity</th> 
«th»Wind Speed</th> 
<th>Summary</th> 
<th>Description</th> 
</tr> 
</thead> 
{{#each cities}} 
<tr> 
<td>{{id}}</td> 
<td>{{name}}</td> 
{{#main}} 
<td>{{temp}}</td> 
<td>{{temp_min}}</td> 
<td>{{temp_max}}</td> 
<td>{{humidity}}</td> 
{{/main}} 
<td>{{wind.speed}}</td> 
{{#each weather}} 
<td>{{main}}</td> 
<td>{{description}}</td> 
{{/each}} 
</tr> 
{{/each}} 
</table> 
</body> 


</html> 
以 上 模板 的 工作 机 制 如 下 。 


。 Handlebars 会 使 用 cities 数组 中 的 数据 来 解析 每 个 标签 。 
。 标签 可 表示 单个 字段 ， 如 {{temp]]。 
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uy 














E 


。 区 块 由 起 始 标签 (如 {{#each cities}}) 和 结束 标签 (如 {{/cities}}) B 
一 一 个 区 块 对 应 一 个 数组 (Zn cities) 或 一 个 对 象 (如 main), 
— each 标签 (如 {{#each cities}}) 用 于 操作 数组 (本 示例 中 为 cities), 


起 来 。 


一 一 个 区 块 为 其 内 部 的 标签 定义 了 上 下 文 。 如 {{main}} 区 块 内 部 的 {{temp}} 标签 即 可 





表示 为 {{main.temp}}， 对 应 ISON 输入 文档 中 的 main.temp 部 分 


3. Handlebars 单 元 测试 
例 7-6 中 的 单元 测试 使 用 Handlebars 模板 将 城市 数据 泻 染 为 HTML，。 


例 7-6  cities-weather-transform-test/test/handlebars-spec.js 
'use strict'; 














声明 : 城市 天 气 数据 由 0penWeatherMap API 通 过 
Creative Commons Share A Like 许 可 证 发 布 。 
为 兼容 json-server， 数 据 经 过 了 一 定 的 修改 。 
此 操作 并 不 意味 着 得 到 了 许可 方 的 背书 。 


此 代码 通过 Creative Commons Share A _ Like 许可 证 发 布 。 











*/ 


var expect = require('chai').expect; 
var jsonfile = require('jsonfile'); 

var fs = require('fs'); 

var handlebars = require('handlebars'); 


describe('cities-handlebars', function() { 
var jsonCitiesFileName = null; 
var htmlTemplateFileName = null; 


beforeEach(function() { 
var baseDir =  dirname + '/../..'; 


jsonCitiesFileName = baseDir + '/data/cities-weather-short.json'; 
htmlTemplateFileName = baseDir + 
' [templates/transform-html.hbs' ; 


})s 


it('should transform cities JSON data to HTML', function(done) { 
jsonfile.readFile(jsonCitiesFileName, function(readJsonFileError, 
jsonObj) { 
if (!readJsonFileError) { 
fs.readFile(htmlTemplateFileName, 'utf8', function( 
readTemplateFileError, templateFileData) { 
if (!readTemplateFileError) { 
var template - handlebars.compile(templateFileData); 
var html = template(jsonObj); 


console. log('\n\n\nHTML Output:\n' + html); 
done(); 

} else { 
done(readTemplateFileError); 


} 
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335 
) else ( 
done(readJsonFileError); 





ER TEL T2530, 3x— Handlebars 单元 测试 与 之 前 相应 的 Mustache 单元 测试 基本 相同 。 
。 无 须 将 从 fs.readFile() 读 取 的 Handlebars 模板 转换 为 字符 串 。 
。 演 染 模板 的 操作 分 为 两 步 。 
— handlebars.compile() 对 模板 进行 编译 ， 并 将 结果 保存 到 template 变量 中 。 
— template() 将 输入 的 ISON 对 象 json0bj iE 2px, HTML, 
使 用 npm test 运行 以 上 测试 后 ， 可 以 看 到 另 一 个 与 目标 HTML. 文档 相似 的 结果 。 
4. Handlebars 在 线 测试 器 
TryHandlebars 和 Architect 是 两 个 非常 优秀 的 在 线 测 试 工具 ， 
的 迭代 开发 与 测试 工作 。 


使 用 TryHandlebars 上 时， 可 以 将 Handlebars 模板 和 JSON 粘贴 到 相应 的 文本 输入 框 中 ， 如 
图 7-2 所 示 。 























可 用 于 简化 Handlebars 模板 








e 


Oy Handlebars.js in your v x 


ECAC 


tryhandlebarsjs.com 





Try Handlebars.js right now in your browser 
Handlebars.js is a sweet javascript library for building clean logicless templates based on the Mustache Templating Language. 


Examples handlebar expression 





Engine Handlebars v4.0.3 


Handlebars Templ. 





Context (JavaScript literal or JSON! 


Register Helper functions (if any) 





5 


Rancho Palos Verdes", 











HTML Source Output 








HTML Preview 


<!DOCTYPE html» OpenWeather - California Cities 
<html> 
C t Li High 
ID City re res z Humidity 
Temp Temp Temp 
charset="UTF-8" 
penWeather - California Cities</title> Rancho 
5386035 Palos 84.34 78.8 93 58 
Verdes 








7-2; TryHandlebars.js: 使 用 Handlebars 将 JSON 转换 为 HTML 





| ^ 


第 7 章 


除了 TryHandlebars， 还 可 以 使 用 Architect 模板 编辑 器 。 在 Architect 的 引擎 下 拉 选 框 中 选 
ff Handlebars.js， 然 后 将 Handlebars 模板 和 输入 的 ISON 分 别 粘贴 到 相应 的 区 域 中 ， 即 可 


看 到 如 图 7-3 所 示 的 结果 。 














© © © / Harchitect - Javascript Ter x Tom 
€ Q fi & https://rowno.github.io/architect/ 
Architect Edit Javascript templates in various engines emre 
Engine: | Handlebars.js $|| Q Reset |» EET) 1.3.0 » E 13.9KB » github » download 
Template View 
1 «!DOCTYPE html» 1-{ 
2» «html» 2- cities": [t | 
3 3 "id": 5386035, 
4~ <head> 4 "name": "Rancho Palos Verdes", 
5 «meta charset-"UTF-8" /» 5- "coord": { 
6 <title>OpenWeather - California Cities</title> 6 "Lon": -118.387016, 
7 </head> 7 "Lat": 33.744461 
8- <body> 8 h 
9 <hl>0penWeather - California Cities</hl> 9- "main": ( 
10- «table class-"weatherTable"» 10 "temp": 84.34, 
11- <thead> 11 "pressure": 1012, 
12 ~ <tr> 12 "humidity": 58, 
13 «th»ID«/th» 13 temp min": 78.8, 
14 <th>City</th> 14 temp_max": 93 
15 <th>Current Temp</th> 15 h 
1R ethstiaw Tamne /th 18 PAH". 1447171072 
Result 
3 
4- <head> 
5 «meta charset-"UTF-8" /» 
6 <title>OpenWeather - California Cities</title> 
7 </head> 
8- <body> 
9 «hi»0penWeather - California Cities</hl> 
10- «table class-"weatherTable"» 
11- <thead> 
i2- «tr» 
13 «th»ID«/th» 
14 <th>City</th> 
15 «th»Current Temp</th> 
16 <th>Low Temp</th> 
17 <th>High Temp</th> 
T esum di ex 6h 
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5. 在 命令 行 中 使 用 Handlebars 
还 可 以 在 命令 行 中 直接 使 用 Handlebars。 如 果 已 经 安装 Node.js， 则 可 以 通过 全 局 安装 hb- 
interpolate 模块 (可 在 GitHub 上 找到 该 模块 ) 来 启用 该 操作 : 


npm install -g hb-interpolate 
cd chapter-7 


hb-interpolate -j ./data/cities-weather-short.json V 
-t ./templates/transform-html.hbs » output.html 


6. 在 其 他 平台 上 使 用 Handlebars 
Handlebars 有 着 很 好 的 跨 平 台 支 持 。 支 持 的 平台 包括 : 


。 Node.js 
* Ruby on Rails 


* Java 


7. Handlebars 记 分 结果 
基于 本 章 开 头 的 评估 标准 ， 表 7-2 展示 了 Handlebars 的 记分 结果 。 
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表 7-2: Handlebars 记 分 结果 




















关注 度 Y 
开发 社区 Y 
平台 JavaScript, Node.js, Java, Ruby on Rails 
易于 入 门 Y 
标准 N 














Handlebars 是 另 一 个 广 为 使 用 的 优秀 引擎 。 Ej Mustache 一 样 ，Handlebars 不 是 一 项 标准 ， 
但 它 也 提供 了 可 靠 的 说 明文 档 并 能 够 跨 平台 工作 。 


7.4.4 转换 工具 评估 一 一 总 结 概要 

对 于 将 JSON 转换 为 HTML WERE UL, Mustache 和 Handlebars 都 是 不 错 的 选择 ， 使 用 
哪 一 个 都 可 以 满足 需求 。 

介绍 了 将 JSON 转换 为 HTML 的 操作 后 ， 接 下 来 本 章 将 介绍 JSON 格式 的 转换 。 


7.5 ”JSON 格式 转换 


只 要 在 任何 像样 点 的 地 方 和 APT 打 过 一 段 时 间 交 道 ， 你 就 应 该 意识 到 API 并 不 是 总 能 如 
预期 那样 工作 。 在 设计 API 时 ，API 所 返回 的 JSON 响应 经 常 成 为 最 被 忽视 的 一 部 分 ， 而 
API 所 返回 的 数据 很 多 时 候 也 是 极为 难 用 的 。 即 使 返回 的 数据 经 过 精心 设计 ， 你 也 可 能 只 
想 读 取 其 中 一 部 分 内 容 ， 或 者 需要 将 数据 转换 成 男 一 种 JSON 结构 以 方便 应 用 程序 读 取 。 
与 第 6 章 中 的 讨论 类 似 ， 可 以 通过 以 下 方法 来 解决 这 一 问题 。 

。 解析 API 返 回 的 JSON， 并 程序 化 地 操作 结构 体 。 

。 手工 编写 代码 ， 将 输入 的 JSON 文档 转换 为 另 一 种 JSON 结构 。 


可 惜 这 些 方案 既 繁琐 又 难 用 。 事 实 上 ， 现 成 的 类 库 可 以 替 你 完成 大 部 分 工作 ， 因 此 根本 无 
须 手 工 编写 类 似 的 工具 代码 。 


7.5.1 存在 的 问题 


TE ISON 格式 转换 操作 上 ， 我 发 现 最 大 问题 在 于 : 标准 缺失 (无 论 是 官方 标准 还 是 事实 标 
准 )。 以 之 前 章节 中 的 JSONPath 为 例 ， 虽 然 它 不 是 官方 标准 ， 却 是 事实 标准 。 作 为 一 门 查 
询 语言 ，JSONPath 有 着 广泛 的 接受 度 ， 在 多 个 平台 上 也 都 有 自己 的 实现 。 但 对 于 ISON $ 
换 类 库 来 说 ， 已 有 的 类 库 大 多 是 某 个 语言 /平台 上 的 单一 实现 ， 很 难 找到 例外 。 我 曾 在 技 
术 社 区 中 寻找 过 超越 单个 平台 的 、 更 加 通用 的 产品 。 这 个 寻找 最 佳 方案 的 过 程 是 一 次 难忘 
的 经 历 ， 但 最 后 我 却 发 现 多 个 ISON 转换 类 库 并 存 比 单一 方案 更 好 ， 和 希望 这 些 类 库 能 对 你 
的 项 目 产 生 帮 助 。 


7.5.2 ”JSON 格 式 转换 类 库 
能 够 对 ISON 文档 进行 格式 转换 的 类 库 有 很 多 。 本 节 将 着 重 介 绍 以 下 几 个 类 库 ; 
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。 JSON Patch 
e JSON-T 

* Mustache 

* Handlebars 


先 揭晓 结论 : Handlebars 是 JSON 格式 转换 的 最 佳 选 择 ( 详 见 7.5.8 节 和 7.59 55), REF 
来 ,我们 将 一 一 介绍 这 些 ISON 格式 转换 技术 ， 曾 明 为 何 Handlebars 是 最 住 选择 。 


7.5.3 ”其 他 优秀 工具 
用 于 ISON 格式 转换 的 类 库 有 很 多 ， 本 书 无 法 详细 介绍 所 有 的 类 库 。 以 下 是 另外 3 个 值得 
了 解 的 类 库 。 
Jolt 
Jolt 只 在 Java 环境 中 工作 。 


Json2Json 
Json2Json 只 有 Node.js 版 本 。 





























jsonapter 
jsonapter 使 用 包含 转换 规则 的 外 部 模板 文件 ， 以 声明 式 的 风格 转换 JSON 数据 格式 。 外 
部 模板 文件 与 XSL 比较 像 ， 但 也 仅 止 于 比较 像 而 已 。jsonapter 及 其 模板 规则 都 使 用 纯 
JavaScript 来 编写 ，XSL 则 拥有 自己 的 模板 语言 。 遗 憾 的 是 ，jsonapter 只 在 JavaScript 
和 Node.js 环境 中 工作 。 


7.5.4 目标 JSON 输 出 


关于 输入 数据 ， 可 参见 7.3 节 中 的 内 容 。 该 数据 的 cities 数组 只 包含 3 个 元 素 ， 但 即使 是 
这 样 的 数据 ， 对 我 们 的 需求 来 说 也 过 于 复杂 。 我 们 不 想 使 用 所 有 的 字段 ， 因 此 需要 执行 以 
下 步骤 来 简化 数据 结构 。 

。 保留 cities 数组 中 的 id 和 name 字段 。 

。 创建 一 个 全 新 的 、 遍 平 的 weather 对 象 。 

。 从 其 他 结构 中 将 有 关 天 气 的 字段 移 到 weather HRA. 


— main.temp, main.humidity, main.temp min, main.temp max 














= 

















— wind.speed 

— weather.0.main 和 weather.0.description 
。 为 简洁 起 见 ， 修 改 字 段 名 。 
基于 这 些 规 则 ， 处 理 后 的 输出 应 当 如 例 7-7 所 示 。 


例 7-7  data/cities-weather-short-transformed.json 


{ 


"cities": [ 




















"id": "5386035", 
"name": "Rancho Palos Verdes", 
"weather": { 
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"currentTemp": 84.34, 
"lowTemp": 78.8, 
"hiTemp": 93, 
"humidity": 58, 
"windSpeed": 4.1, 
"summary": "Clear", 
"description": "Sky is Clear" 
} 
}, 
{ 


"id": "5392528", 
"name": "San Pedro", 
"weather": { 
"currentTemp": 84.02, 
"lowTemp": 78.8, 
"hiTemp": 91, 
"humidity": 58, 
"windSpeed": 4.1, 
"summary": "Clear", 
"description": "Sky is Clear" 


}， 
t 


"id": "3988392", 

"name": "Rosarito", 

"weather": { 
"currentTemp": 82.47, 
"lowTemp": 78.8, 
"hiTemp": 86, 
"humidity": 61, 
"windSpeed": 4.6, 
"summary": "Clouds", 
"description": "scattered clouds" 

} 

} 
] 
} 


我 们 会 使 用 不 同 的 JSON 格式 转换 类 库 将 示例 ISON 输入 数据 转换 为 目标 JSON 输出 ， 并 
根据 操作 的 难 易 程度 来 评估 每 个 JSON 类 库 。 

















7.5.5 JSON Patch 


作为 一 项 IETF 标准 ，JSON Patch 定义 了 一 种 数据 格式 ， 用 于 表示 对 资源 的 转换 操作 。 
JSON Patch 可 以 与 HTTP PATCH 标准 协同 工作 。 设 计 HTTP PATCH 的 目的 在 于 修改 由 
API 所 提供 的 资源 。 简 而 言 之 ，HTTP PATCH 可 以 修改 资源 的 部 分 内 容 ，HTTP PUT 则 用 
于 整体 替换 资源 。 


设计 JSON Patch 的 初衷 是 将 其 作为 HTTP 请 求 的 一 部 分 来 考虑 ， 与 HTTP 响应 无 关 。 医 
此 ，JSON Patch 其 实 是 为 API 的 提供 者 所 设计 的 ， 考 虑 的 并 不 是 API 使 用 者 的 需求 。 但 本 
章 是 从 API 使 用 者 的 角度 来 描述 的 ， 因 此 我 们 会 探讨 使 用 JSON Patch 对 HITP 响应 中 的 
数据 进行 转换 的 操作 。 
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1. JSON Patch 语 法 
表 7-3 展示 了 能 够 用 于 处 理 OpenWeatherMap 数据 的 一 些 JSON Patch 操作 。 


表 7-3: JSON Patch 操 作 























JSON Patch 操 作 描述 

添加 - { "op": "add", "path": "/wind", "value": ”在 已 存在 的 对 象 或 数组 中 添加 数据 。 不 能 使 用 该 操 
{ "direction": "W" } } 作 在 文档 中 增加 全 新 的 对 象 

删除 - { "op": "remove", "path": "/main" } 删除 main 对 象 





替换 - ( "op": "replace", "path": "/weather/0/ 替换 文档 中 的 某 个 值 。 该 操作 等 
main", "value": "Rain" } 然后 再 进行 add 
复制 - { "op": "copy", "from": "/main/temp", 将 某 个 字段 的 值 复制 到 另 一 处 地 方 
"path": "/weather/0/temp" } 





























价 于 先 做 remove, 





移动 - ( "op": "move", "from": "/main/temp", 将 main 对 象 中 的 temp 名 称 - 值 对 移动 到 weather 数 





"path": "/weather/0/temp" } 组 中 














如 需 全 面 了 解 SON Patch， 可 访问 其 官方 网 站 。JSON Patch 中 的 path 值 和 from 值 均 遵循 








了 第 6 章 中 提 及 的 ISON Pointer 标准 。 
2. JSON Patch 单 元 测试 











例 7-8 中 的 单元 测试 展示 了 实际 应 用 中 的 转换 操作 。 这 段 代码 使 用 了 JSON Patch 的 Node.js 





模块 。 可 访问 该 模块 的 GitHub 主页 获取 更 多 信息 。 





该 单元 测试 展示 了 如 何 使 用 JSON Patch 将 城市 天 气 数据 转换 为 目标 ISON 数据 结构 。 





例 7-8  cities-weather-transform-test/test/json-patch-spec.json 
'use strict'; 








/* 声明 : 城市 天 气 数据 由 0penWeatherMap API 通 过 
Creative Commons Share A _ Like 许可 证 发 布 。 
为 兼容 json-server， 数 据 经 过 了 一 定 的 修改 。 
此 操作 并 不 意味 着 得 到 了 许可 方 的 背书 。 


此 代码 通过 Creative Commons Share A Like 许 可 证 发 布 。 
* 
/ 











var expect = require('chai').expect; 
var jsonfile - require('jsonfile'); 
var jsonpatch - require('json-patch'); 


var citiesTemplate - [ 
{ 
op: 'remove', 
path: '/coord' 


}, 

{ 
op: 'remove', 
path: '/dt' 

{ 


op: 'remove', 
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path: '/clouds' 
} 
{ 
op: 'remove', 
path: '/weather/0/id' 
s 
{ 
op: 'remove', 
path: '/weather/0/icon' 
{ 
op: 'move', 
from: '/main/temp', 
path: '/weather/0/currentTemp' 
} 
{ 
op: 'move', 
from: '/main/temp min', 
path: '/weather/0/lowTemp' 
} 
{ 
op: 'move', 
from: '/main/temp_max', 
path: '/weather/0/hiTemp' 
} 
{ 
op: 'move', 
from: '/main/humidity', 
path: '/weather/0/humidity' 
} 
{ 
op: 'move', 
from: '/weather/0/main', 
path: '/weather/0/summary' 
J; 
{ 
op: 'move', 
from: '/wind/speed', 
path: '/weather/0/windSpeed' 
J; 
{ 
op: 'remove', 
path: '/main' 
{ 
op: 'remove', 
path: '/wind' 
} 
l; 
describe('cities-json-patch', function() { 
var jsonFileName - null; 


var jsonCitiesFileName - null; 


beforeEach(function() { 
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var baseDir =  dirname + '/../../data'; 


jsonCitiesFileName = baseDir + '/cities-weather-short.json'; 


p); 


it('should patch all cities - fail', function(done) { 
jsonfile.readFile(jsonCitiesFileName, function(fileReadError, 
json0bj) { 
if (!fileReadError) { 
try { 
var output = jsonpatch.apply(jsonObj, citiesTemplate); 


console. log('\n\n\n\Original JSON'); 
console.log(json0bj); 

console. log('\n\n\n\Patched JSON'); 

console. Log(JSON.stringify(output, null, 2)); 
done(); 

} catch (transformError) { 
console.error(transformError); 
done(transformError); 

} 

} else { 

console.error(fileReadError); 

done(fileReadError); 


p; 


在 以 上 示例 中 ， 测 试 代码 运行 了 一 次 ISON Patch 的 转换 操作 。 可 以 在 命令 行 中 执行 以 下 命 
令 来 运行 该 测试 : 


cd cities-weather-transform-test 








npm test 


正如 接 下 来 将 看 到 的 ，should patch all cities - fail 这 一 测试 用 例会 失败 ， 结 果 如 下 
所 示 : 

cities-json-patch 

( [PatchConflictError: Value at coord does not exist] 

message: 'Value at coord does not exist', 


name: 'PatchConflictError' } 
1) should patch all cities - fail 


在 该 测试 用 例 中 ， 因 为 内 在 的 JSON Pointer 规则 只 能 识别 对 象 ， 无 法 识别 集合 ， 所 以 
JSON Patch 无 法 找到 路 径 为 /coord 的 资源 。 


例 7-9 是 另 一 个 几乎 能 工作 的 单元 测试 。 
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例 7-9  cities-weather-transform-test/test/json-patch-spec.json 


describe('cities-json-patch', function() { 
var jsonFileName - null; 
var jsonCitiesFileName - null; 


beforeEach(function() { 
var baseDir =  dirname + '/../../data'; 


jsonCitiesFileName = baseDir + '/cities-weather-short.json'; 


H; 


it('should patch all cities - success (kind of)', function(done) { 
jsonfile.readFile(jsonCitiesFileName, function(fileReadError, 
json0bj) { 
if (!fileReadError) { 
try { 

console. log('\n\n\n\Original JSON'); 
console. Log(json0bj); 
var output = []; 


for (var i in jsonObj['cities']) { 
output.push(jsonpatch.apply(jsonObj['cities'][i], 
citiesTemplate)); 


} 


console. log('\n\n\n\Patched JSON'); 
console. log(JSON.stringify(output, null, 2)); 
done(); 

} catch (transformError) { 
console.error(transformError); 
done(transformError); 

} 

} else { 
console.error(fileReadError); 
done(fileReadError); 
} 
25 
IDE 


p); 


虽然 should patch all cities - success (kind of) 这 一 测试 用 例 能 够 成 功 运行 ， 但 由 于 

以 下 原因 ， 该 测试 并 不 能 有 效 工 作 。 

。 我 们 想 要 创建 新 的 weather 对 象 ， 而 不 仅仅 只 是 使 用 已 有 的 数组 。 遗 憾 的 是 ， 使 用 
JSON Patch 无 法 实现 这 一 点 。 

。 该 测试 代码 会 遍历 输入 的 JSON， 然 后 转换 cities 数组 中 的 每 个 元 素 ， 最 后 再 将 所 有 的 
结果 组 装 到 output 数组 中 。 这 么 操作 的 原因 是 ,JSON Patch 只 能 用 于 处 理 单个 资源 (对 
象 ) ， 无 法 处 理 集合 (BA). 








— 
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3. 在 其 他 平台 上 使 用 JSON Patch 
为 是 一 项 标准 ， 所 以 JSON Patch 有 着 不 错 的 跨 平台 支持 。 除 Node.js 外 ，JSON Patch X 
持 的 平台 还 包括 ; 


。 Java 
* Ruby 


如 需 了 解 更 多 支持 的 平台 和 类 库 ， 可 参考 JSON Patch 网 站 。 


4. JSON Patch 记 分 结果 
基于 本 章 开头 的 评估 标准 ， 表 7-4 展示 了 ISON Patch 的 记分 结果 。 
387-4: JSON Patch 记 分 结果 




















关注 度 Y 

开发 社区 Y 

平台 JavaScript, Node.js, Java, Ruby on Rails 
易于 入 门 N 

标准 Y — RFC 6902 














5. JSON Patch 的 局 限 性 
JSON Patch 存在 以 下 局 限 性 。 


。 JSON Patch 不 允许 添加 全 新 的 数据 结构 ， 只 允许 对 已 有 的 结构 和 数据 进行 修改 。 

。 JSON Patch 设计 用 于 修改 单个 对 象 , 没 有 考虑 到 对 数组 的 处 理 问题 。 这 么 做 的 原因 在 于 : 
JSON Patch 使 用 JSON Pointer 来 搜索 数据 ， 而 JSON Pointer 查询 语句 只 能 返回 JSON 文 
档 中 的 单个 字段 。 

虽然 JSON Patch 的 初衷 并 不 是 对 HTTP 响应 中 的 ISON 数据 进行 转换 ， 但 这 样 的 操作 值得 

一 试 。JSON Patch 真正 的 初衷 是 与 HTTP PATCH 配合 使 用 ， 对 HTTP 请 求 中 的 资源 数据 

进行 部 分 修改 ,用 JSON 来 声明 具体 的 修改 规则 。 


相 比 于 JSON Patch， 还 可 以 使 用 更 好 的 类 库 将 一 个 ISON 转换 为 另 一 种 JSON 数据 结构 。 
接 下 来 我 们 尝试 一 下 JSON-T。 


























7.5.6 JSON-T 


JSON-T 由 JSONPath 的 创建 者 Stefan Goessner 于 2006 年 开发 ， 是 早期 的 JSON 转换 类 库 
之 一 。JSON-T 与 XML 中 的 XSLT 比较 像 ， 都 使 用 了 包含 转换 规则 的 模板 文件 。 
1. JSON-T 语 法 
JSON-T 使 用 在 JavaScript 对 象 字 面 量 中 定义 的 转换 规则 ， 其 中 每 条 规则 都 和 对 象 中 的 一 个 
名 称 一 值 对 对 应 。 规 则 的 形式 如 下 : 


var transformRules = { 
'ruleName': 'transformationRule', 
'ruleName': function 
































JSON 转 换 | 177 


对 于 以 上 形式 ， 需 要 注意 以 下 几 点 。 
。 每 个 ruleName 或 transformationRule 都 必须 由 单 引 号 ('…) 或 双 引 号 ("") 括 起 来 。 


。 每 个 transformationRule 都 有 由 大 括号 括 起 来 的 一 条 或 多 条 转换 表达 式 ， 如 {cities}, 
。 转换 表达 式 可 解析 为 另 一 个 ruleName 或 文档 中 的 某 个 字段 , 即 数组 、 对 象 或 名 称 - 值 对 。 


以 下 示例 展示 了 用 于 转换 OpenWeatherMap 数据 的 JSON-T 规则 : 


var transformRules = { 
'self': '{ "cities": [{cities}] }', 
'cities[*]': '( "id": "(S.id)", "name": "($.name]", ' + 
'""weather": ( "currentTemp": {$.main.temp}, "lowTemp": ($.main.temp min), ' + 
'""hiTemp": ($.main.temp max), "humidity": ($.main.humidity), ' + 
'""windSpeed": [$.wind.speed), "summary": "($.weather[0].mainj", ' + 
'""description": "(S.weather[0].description]" } },' 








a 
该 示例 的 工作 机 制 如 下 。 


。 self 是 声明 新 的 JSON 文档 格式 的 最 高 级 规则 ， 其 中 {cities} 会 引用 cities[*] 规则 的 
返回 结果 。 
。 cities[*] 规则 声明 如 何 对 cities 数组 进行 格式 化 。 
一 cities[*] 规则 中 的 星 号 表示 该 规则 作用 于 cities 数组 元 素 。 
一 * 解析 为 每 个 数组 的 索引 。 
— 全.} 是 一 种 快捷 表示 法 。{S.name} 规则 告诉 JSON-T 从 每 个 cities 数组 元 素 的 name 
字段 中 抽取 数据 ， 完 整 的 表示 则 为 : ctttes[*].name。 
可 以 访问 JSON-T 官方 网 站 中 的 “Basic Rules” 部 分 来 了 解 所 有 的 转换 规则 文档 。 
2. JSON-T 单 元 测试 
例 7-10 中 的 单元 测试 使 用 jsont 这 一 Node.js 模块 来 展示 JSON-T 的 使 用 。 


例 7-10 cities-weather-transform-test/test/jsont-spec.js 
'use strict'; 




















声明 : 城市 天 气 数据 由 0penWeatherMap API 通 过 
Creative Commons Share A Like 许 可 证 发 布 。 
为 兼容 json-server ， 数 据 经 过 了 一 es 
此 操作 并 不 意味 着 得 到 了 许可 方 的 背 


此 代码 通过 Creative Commons Share A Like 许 可 证 发 布 。 
* 
/ 





























var expect = require('chai').expect; 
var jsonfile = require('jsonfile'); 
var jsonT = require('../lib/jsont').jsonT; 


describe('cities-jsont', function() { 
var jsonCitiesFileName - null; 


var transformRules = { 
'self': '( "cities": [{cities}] }', 
'cities[*]': '{ "id": "{S.id}", "name": "[$.name]", ' + 





weather": { "currentTemp": {$.main.temp}, "lowTemp": ($.main.temp min), 
'""hiTemp": ($.main.temp max), "humidity": {$.main.humidity}, ' + 
'""windSpeed": {$.wind.speed}, "summary": "([S$.weather[0].main]", ' + 
"description": "{$.weather[0].description}" } },' 


+ 


+ 


beforeEach(function() { 


var baseDir =  dirname + '/../../data'; 
jsonCitiesFileName = baseDir + '/cities-weather-short.json'; 
35 


it('should transform cities JSON data', function(done) { 
jsonfile.readFile(jsonCitiesFileName, function(readFileError, 
jsonObj) { 
if (!readFileError) { 
var jsonStr = jsonT(jsonObj, transformRules); 


jsonStr = repairJson(jsonStr); 
console.log(JSON.stringify(JSON.parse(jsonStr), null, 2)); 
done(); 

} else { 
done(readFileError); 





注意 ， 以 上 测试 代码 调用 repairison() 函数 来 生成 合法 的 ISON: 


function repairJson(jsonStr) { 
var repairedJsonStr - jsonStr; 


var repairs = [ 
[/,\s*}/gi, ' }'], 
[/,\s*\]/gi, ' 1'] 
J; 
for (var i = 0, len = repairs.length; i < len; ++i) { 
repairedJsonStr = repairedJsonStr.replace(repairs[i][0], repairs[i][1]); 


j 


return repairedJsonStr; 


} 
// 在 测试 用 例 中 做 如 下 修改 : 








jsonStr = repairJson(jsonStr); 
console.log(JSON.stringify(JSON.parse(jsonStr), null, 2)); 











如 果 不 做 任何 修改 ， 则 JSON-T 会 在 cities 数组 的 最 后 一 个 元 素 后面 添 加 逗号 ， 导 致 转换 
后 的 JSON 非法 。 为 了 修复 这 一 问题 ， 示 例 中 的 repairJson() 函数 使 用 了 正则 表达 式 来 删 
除 闭合 大 括号 0) 或 闭合 数组 符号 (0) 前 的 逗号 。 虽 然 大 多 数 编 程 语言 都 支持 正则 表达 
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式 ， 但 这 种 自行 编写 代码 来 纠正 输出 的 做 法 是 比较 精 糕 的 。 你 不 应 该 再 重复 编写 基础 设施 
代码 。 

3. 在 其 他 平台 上 使 用 JSON-T 

除了 Node.js, JSON-T 还 可 以 在 以 下 平台 上 运行 。 














浏览 器 
JSON-T 能 够 以 单个 JavaScript 文件 jsont.js 的 形式 运行 。 
Ruby 


JSON-T 存在 纯 Ruby 的 实现 。 
我 未 能 找到 ISON-T 的 纯 Java KIL, 
4. JSON-T 记 分 结果 
基于 本 章 开 头 的 评估 标准 ， 表 7-5 展示 了 JSON-T 的 记分 结果 。 
表 7-5: JSON-T 记 分 结果 























关注 度 Y 
开发 社区 Y 
平台 JavaScript, Node.js, Ruby on Rails 
易于 入 门 N 
标准 N 
5. JSON-T 的 局 限 性 
JSON-T 存在 以 下 局 限 性 。 


。 过 于 复杂 的 语法 。 

。 没有 Java 实现 。 

。 无 法 处 理 字 符 串 中 的 转 义 文本 。 例 如 ，JSON-T 会 将 字符 串 "escapedString": "I have 
a V'string within" a string" 转换 为 "escapedString": "I have a "string within " 
a string" 这 样 的 非法 字符 串 ， 导 致 必须 使 用 正则 表达 式 来 修复 结果 。 

。 处 理 数 组 或 对 象 的 最 后 一 个 元 素 有 误 。 

因为 能 够 处 理 整 个 JSON 文档 ， 所 以 JSON-T 相 较 于 JSON Patch 有 了 小 小 的 改进 ; 但 如 果 

想 要 正常 工作 的 话 ，JSON-T 依旧 需要 开发 人 员 编 写 额外 的 代码 。JSON-T 往 正 确 的 方向 前 

进 了 一 步 ， 但 在 实际 的 开发 环境 中 并 未 达到 可 以 应 用 的 程度 。JSON-T 擅长 将 JSON 转换 

为 HIML， 但 其 设计 初 囊 并 不 包括 对 ISON 文档 的 结构 进行 转换 。 


接 下 来 我 们 看 一 下 Mustache。 





























7.5.7 Mustache 


在 前 面 的 内 容 中 ， 我 们 看 到 Mustache 可 以 轻松 地 将 JSON 转换 为 HTML。 接 下 来 的 内 容 将 
展示 如 何 使 用 Mustache 将 城市 数据 转换 为 目标 JSON 文档 。 


例 7-11 是 一 个 进行 转换 的 Mustache 模板 (7.4 节 中 介绍 过 Mustache 模板 的 详细 信息 ) 。 
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例 7-11 templates/transform-json.mustache 


{ 
"cities": [ 
{{#cities}} 


mid": "{{id}}", 

"name": "{{name}}", 

"weather": { 
{{#main}} 
"currentTemp": {{temp}}, 
"LowTemp": {{temp_min}}, 
"hiTemp": {{temp_max}}, 
"humidity": {{humidity}}, 
{{/main}} 
"windSpeed": {{wind.speed}}, 
{{#weather .0}} 
"summary": "{{main}}" 
"description": "{{description}}" 
{{/weather .0}} 

} 

}, 
{{/cities}} 
] 


} 


在 Architect 模板 编辑 器 中 运行 该 模板 。 在 Engine 下 拉 菜 单 中 选择 Mustache.js， 然 后 将 
Mustache 模板 和 输入 的 JSON 粘贴 到 相应 的 文本 框 中 。 可 以 看 到 如 图 7-4 所 示 的 结果 。 














€ GO & Secure https://rowno.github.io/architect/ * 


Architect kai Javascript templates in various engines Con) 








Engine: Mustache.js 4 | C Reset |» ESTES) 0.8.1 » EZ 2.0KB » github » download 
Template View 
mu Ev t 
2 "cities": [ [i "cities": 
3 {{#cities}} 3 "id": 
4 1 4 "name" : 
5 "ü "(id)", 5 coord": { 
6 "name": "{{name}}", 6 "lon": -118.387016, 
7 "weather": { 7 "lat": 33.744461 
8 {{#main}} 8 3, 
9 "currentTemp": {{temp}}, 9- "main": ( 
10 "lowTemp": {{temp_min}}, 10 "temp": 84.34, 
11 "hiTemp": {{temp_max}}, 11 "pressure": 1012, 
12 "humidity": {{humidity}}, 12 "humidity": 58, 
13 {{/main}} 13 "temp min": 78.8, 
14 "windSpeed": {{wind.speed}}, 14 "temp max": 93 
15 {{#weather .0}} 15 了 
16 "summary" "Ifmai nth" 16 "d" 1442171078 
Result 
£o nl 
29 
30 "id": "3988392", 
31 "name": "Rosarito", 
32 "weather": { 
33 "currentTemp": 82.47, 
34 "lowTemp": 78.8, 
35 "hiTemp": 86, 
36 "humidity": 61, 
37 "windSpeed": 
38 "summary" : 
39 "description": "scattered clouds" 
40 } 
41 } 
42 1 
43 } 











& 7-4: 在 Architect 中 用 Mustache 转换 JSON 
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观察 Result 文本 框 中 的 ISON 处 理 结 果 的 第 41 行 ， 我 们 可 以 看 到 多 余 的 辟 号 ， 而 这 会 导 
致 JSON 结果 非法 。 如 果 将 该 JSON 结果 粘贴 到 JSONLint 中 ， 就 可 以 看 到 该 JSON 确实 是 
韭 法 的 : 




















Results 


Expecting 'EOF', ')', 2's", 71^. got ‘STRING 











Mustache 的 局 限 性 
与 JSON-T 一 样 ， 在 处 理 ISON #47 Alt, Mustache 无 法 确定 当前 所 处 理 的 元 素 是 否 为 数组 
或 对 象 中 的 最 后 一 个 元 素 。 因 此 ，Mustache 不 能 完美 地 用 于 处 理 ISON 结构 转换 。 


接 下 来 我 们 开始 介绍 Handlebars。 





7.5.8 Handlebars 


正如 我 们 之 前 所 看 到 的 ，Handlebars 可 以 很 好 地 将 JSON 转换 为 HIML， 例 7-12 中 的 模板 
可 用 于 将 城市 ISON 数据 转换 为 目标 ISON 输出 。 


f 7-12 templates/transform-json.hbs 
{ 
"cities": [ 
{{#each cities}} 


{ 

"id": "{{id}}", 

"name": "{{name}}", 

"weather": { 
{{#main}} 
"currentTemp": {{temp}}, 
"lowTemp": {{temp_min}}, 
"hiTemp": {{temp_max}}, 
"humidity": {{humidity}}, 
{{/main}} 
"windSpeed": {{wind.speed}}, 
{{#each weather}} 


"summary": "{{main}}", 
"description": "{{description}}" 
{{/each}} 


} 
}{{#unless @last}},{{/unless}} 
{{/each}} 
] 


j 


除了 一 处 明显 的 差异 ， 该 模板 与 7.4 节 中 的 Handlebars 所 用 的 模板 很 相似 。 以 下 这 行 代码 
准确 地 实现 了 我 们 的 需求 : 除了 最 后 一 个 元 素 ， 在 所 有 元 素 的 后 面 添加 一 个 逗号 : 
{{#unless @last}},{{/unless}} 








-A 
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以 下 是 对 这 行 代码 的 解释 。 


e {{#unless}} 是 Handlebars 的 内 置 辅 助 指 令 ， 仅 当 


的 代码 块 。 


。 Qlast 是 Handlebars 的 内 置 变量 ， 只 在 当前 元 素 是 数组 中 的 最 后 一 个 元 素 时 才 返 回 














其 条 件 语 名 返回 false MA RAG 





true。 


如 需 了 解 更 多 有 关 {{#unless}} 和 @last 的 信息 ， 可 参考 Handlebars 官方 网 站 。 











在 Architect 模板 编辑 器 中 运行 该 模板 。 在 Engine 下 拉 菜 单 中 选择 Handlebars.js， 然 后 将 


Handlebars 模板 和 输入 的 ISON 粘贴 到 相应 的 文本 框 中 。 可 以 看 到 如 图 7-5 所 示 的 结果 。 





= 


Engine: Handlebars.js 





G 合 @ Secure https://rowno.github.io/architect/ 
Architect kai Javascript templates in various engines CIL: 


$ | Cneset » TRE) 1.3.0 » EZ 13.9KB » github » download 


Template 
o tmang? 
9 "currentTemp": {{temp}}, 
10 "lowTemp": {{temp_min}}, 
11 "hiTemp": {{temp_max}}, 
12 "humidity": {{humidity}}, 
13 {{/main}} 
14 "windSpeed": {{wind.speed}}, 
15 {{#each weather}} 
16 "summary": "{{main}}", 
17 "description": "{{description}}" 
18 {{/each}} 
19 } 
20 }{{#unless @last}}, {{/unless}} 
21 {{/each}} 
22 
23. Y 
Result 
E 
45 "currentTemp": 82.47, 
46 "lowTemp": 78.8, 
47 "hiTemp": 86, 
48 "humidity": 61, 
49 
50 "windSpeed": 4.6, 
51 
52 "summary": "Clouds", 
53 "description": "scattered clouds" 
54 
55 H 
56 } 
57 
58 J 
59 ) 


* 

View 

i-f 

2 "cities": [f 

3 "id": 5386035, 

4 "name": "Rancho Palos Verdes", 

me "coord": { 

6 "lon": -118.387016, 

7 "lat": 33.744461 

8 3, 

9- "main": ( 

10 "temp": 84.34, 

11 "pressure": 1012, 

12 "humidity": 58, 

13 "temp min": 78.8, 

14 "temp max": 93 

15 D? 

16 "dt". 1442171078 








B 7-5: f£ Architect 中 用 Handlebars 转换 JSON 


观察 Result 文本 框 中 的 ISON 处 理 结果 的 第 56 行 ， 我 们 可 以 看 到 多 余 的 逗号 消失 了 ， 





因 


此 处 理 后 的 JSON 是 合法 的 。 如 果 将 这 一 JSON 结果 粘贴 到 JSONLint 中 ， 可 以 看 到 该 








JSON 确实 是 合法 的 ， 如 图 











7-6 所 示 。 
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1 { 
2 cities”: [ 
4 { 


"id": "5386035", 
"name": "Rancho Palos Verdes", 
"weather": ( 
"currentTemp": 84.34, 
"lowTemp": 78.8, 
1 "hiTemp": 93, 
"humidity": 58, 


BI "windSpeed": 4.1, 


"summary": "Clear", 
"description": "Sky is Clear" 


Validate JSON Clear 


Results 


Valid JSON 











7-6: 用 JSONLint 校 验 经 过 Handlebars 处 理 后 的 JSON 结果 


这 样 的 结果 正 是 我 们 所 探寻 的 。 就 像 我 们 之 前 所 提 到 的 那样 ，Handlebars 与 Mustache 的 区 
别 在 于 : Handlebars 中 存在 足 量 的 控制 逻辑 ， 能 够 使 得 ISON 结构 转换 正常 进行 。 


7.5.9 ”转换 工具 评估 一 一 总 结 概要 


根据 评估 标准 和 总 体 的 可 用 性 ，Handlebars 是 我 在 ISON 结构 转换 领域 最 为 偏爱 的 工具 ， 
原因 有 以 下 几 点 。 


e Handlebars 是 唯一 一 个 不 用 编写 额外 处 理 代码 的 类 库 。 其 内 置 的 条 件 逻 辑 使 得 这 一 点 成 
为 可 能 。 

。 跨 平台 支持 性 较 好 。 

。 模板 语言 丰富 ， 能 够 满足 大 多 数 的 转换 需求 。 

。 它 是 声明 式 的 ， 但 也 支持 在 自 定义 辅助 指令 中 编写 额外 的 逻辑 代码 。 

。 优秀 的 在 线 工 具 使 得 开发 工作 变 得 更 加 便捷 。 

介绍 了 JSON 结构 转换 后 ， 接 下 来 本 章 将 描述 从 JSON 转换 为 XML 的 操作 。 














A 
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7.6 JSON 与 XML 的 相互 转换 


开发 者 和 架构 师 经 常会 磁 到 需要 与 遗留 系统 进行 整合 的 情况 ， 而 这 些 遗 留 系统 可 能 仍 在 
使 用 XML。 为 了 实现 完美 的 关注 点 分 离 ， 在 自己 的 系统 边缘 增加 薄 薄 的 适 配 层 以 负责 对 
XML 和 JSON 进行 相互 转换 ， 无 疑 是 十 分 重要 的 。 


7.6.1 传统 转换 工具 


在 XML 元 素 (如 <weather>) 和 JSON 之 间 进 行 相互 转 换 是 一 件 比较 简单 的 事情 ， 但 在 
XML 属性 和 JSON 之 间 进 行 相互 转换 就 比较 困难 了 。 因 为 “属性 的 表示 ”在 JSON 中 缺乏 
标准 ， 所 以 XML 属性 和 JSON 之 间 的 相互 转换 是 一 种 有 损 转 换 ， 即 无 法 将 转换 后 的 JSON 
重新 转换 成 初始 的 XML， 反 之 亦 然 。 切 记 ，JSON 的 核心 组 成 结构 是 对 象 、 数 组 和 名 称 - 
值 对 。 


比如 ，XML 属性 用 于 提供 描述 元 素 的 元 数据 ， 大 致 如 下 所 示 : 


<weather temp="84.34" pressure="1012" humidity="58" 
temp_min="78.8" temp_max="93"/> 



































在 这 一 XML HEt, temp, pressure, humidity, temp_min 和 temp max 属性 描述 了 weather 
元 素 。 在 过 去 XML 还 很 流行 的 时 候 (2 1998-2008 4E), XML Schema 的 很 多 设计 人 员 将 
XML 属性 用 于 : 


。 减少 在 网 络 上 传输 的 消息 的 总 体 大 小 ， 
。 简化 XML 和 平台 (如 Java, JavaScript, Ruby 或 C#) 之 间 的 转换 工作 。 


我 们 将 介绍 如 何在 XML 和 JSON 之 间 进 行 直接 转换 ， 以 下 是 一 些 知名 的 传统 转换 工具 : 


e Badgerfish 
。 Parker 

e JsonML 

。 Spark 

* GData 

e Abdera 


因为 Badgerfish 和 Parker 的 知名 度 较 高 ， 所 以 本 章 将 主要 介绍 这 两 个 工具 。 详 尽 谈 论 、 
深入 比较 上 述 XML-JSON 相互 转换 的 工具 超出 了 本 书 的 探讨 范围 ， 相 关 详 情 可 参考 the 
Open311 wiki。 


为 了 比较 Badgerfish 和 Parker， 我 们 先 展示 一 个 基于 OpenWeatherMap 数据 的 示例 XML 文档 。 
然后 ， 我 们 将 比较 这 两 个 工具 是 如 何 将 XML 转换 成 SON 的 。 例 7-13 展示 了 输入 的 XML。 


例 7-13  data/cities-weather-short.xml 
<?xml versionz"1.0" encoding="UTF-8" ?> 
«cities» 
«city» 
<id>5386035</id> 
<name>Rancho Palos Verdes</name> 





























JSON 转 换 | 185 


«coord» 
«lon»-118.387016«/lon» 
«lat»33.744461«/lat» 

</coord> 

<main temp="84.34" pressure="1012" humidity="58" 

<dt>1442171078</dt> 

<wind> 
<speed>4.1</speed> 
<deg>300</deg> 

</wind> 

<clouds> 
<all>5</all> 

</clouds> 

<weather> 
<id>800</id> 
<main>Clear</main> 
<description>Sky is Clear</description> 
<icon>02d</icon> 

</weather> 

</city> 
<city> 

<id>5392528</id> 

<name>San Pedro</name> 

<coord> 
«lon»-118.29229«/lon» 
«lat»33.735851«/lat» 
</coord> 

<main temp="84.02" pressure="1012" humidity="58" 

<dt>1442171080</dt> 

<wind> 
<speed>4.1</speed> 
<deg>300</deg> 

</wind> 

<clouds> 

<all>5</all> 
</clouds> 

<weather> 
<id>800</id> 
<main>Clear</main> 
<description>Sky is Clear</description> 
<icon>02d</icon> 

</weather> 

</city> 
<city> 

<id>3988392</id> 

<name>Rosarito</name> 

<coord> 
«lon»-117.033333«/lon» 
«lat»32.333328«/lat» 
</coord> 

<main temp="82.47" pressure="1012" humidity="61" 

<dt>1442170905</dt> 

<wind> 
«speed»4.6«/speed» 
«deg»240«/deg» 


temp min-z"78.8" temp maxz"93"/» 


temp min-"78.8" temp maxz"91"/» 


temp min-"78.8" temp max-"86"/» 
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</wind> 
<CLouds> 
<all>32</all> 
</clouds> 
<weather> 
<id>802</id> 
<main>Clouds</main> 
<description>scattered clouds</description> 
<icon>03d</icon> 
</weather> 
</city> 
</cities> 


1. Badgerfish 
Badgerfish 提供 了 非常 优秀 的 在 线 测试 器 ， 能 有 效 简 化 将 输入 的 XML 转换 为 SON 的 操 
fg, Fd 7-7 展示 了 Badgerfish Online Tester, 

















eo00/;n XML to JSON x V 
E C (Y | Q dropbox.ashlock.us/open31 1/json-xml/ * H6 gba! 
Convert XML to JSON 





<?xml version="1.0" encoding="UTF-8" ?> 
«cities» 
city» 
<id>5386035<jid> 
<name>Rancho Palos Verdes</name> 
oord> 
<lon>-118.387016</lon> 
<lat>33.744461</lat> 
</coord 
Translate XML above to JSON below 











788; temp. max": 9' 
"icon": { "$1": "02d" » Rosai 3328 } }, temp. mi 
“788 “@temp.max 86) "it hen 1442170905 }, "wind VEI Esi 4.6" }, "deg" e$ 2403), "clouds" Cai do $i 32) ), "weather ("id ss 602). pun (CST: "Clouds" j, "description": ("St "scattered 
clouds" }, "icon" 














& 7-7. Badgerfish 在 线 测试 器 一 一 将 XML 转换 为 JSON 





将 输入 的 XML 粘贴 到 Convert XML to JSON 标题 下 的 文本 输入 框 中 ， 点 击 Translate XML 
above to JSON below button 按钮 ， 即 可 在 结果 文本 框 中 看 到 非常 紧凑 的 JSON。 可 以 使 用 
JSONLint 或 包含 JSON 优化 显示 插件 的 任何 文本 编辑 器 ， 处 理 后 即 可 看 到 更 具 可 读 性 的 
JSON 结果 ， 如 例 7-14 所 示 。 


例 7-14  data/cities-weather-short-badgerfish.json 
{ 



































"cities": { 
"city" : [t 
"id": { 
"$1": 5386035 


name": { 

"$1": "Rancho Palos Verdes" 
I 
"coord": ( 
"lon": { 

"$1": "-118.387016" 

}, 

"Lat": { 

"$1": "33.744461" 
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main": { 
"@temp": "84.34", 
"@pressure": 1012, 
"@humidity": 58, 
"@temp_min": "78.8", 
"@temp_max": 93 


}, 
"dt": { 

"$1": 1442171078 
}, 
"wind": { 

"speed" { 

"$1" "4.1" 
) 


"$1" : 300 


}, 
"clouds": { 
"all": { 
"$1": 5 
j 
}, 
"weather": { 
"Gd": { 
"$1": 800 


main": { 
"$1": "Clear" 
}， 
"description": ( 
"$1": "Sky is Clear" 
}, 
"icon": { 
"$1" y "02d " 
} 
} 
Lt 
"id": { 
"$1": 5392528 
}, 
"name": { 
"$1": "San Pedro" 
}, 
"coord": { 
"Lon": { 
"$1": "-118.29229" 
}， 
"lat": { 
"$1": "33.735851" 
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"Qtemp": "84.02", 
"Qpressure": 1012, 
"@humidity": 58, 
"Qtemp min": "78.8", 
"(temp max": 91 

F: 

"dt": { 
"$1": 1442171080 


speed": { 
"$1": "4.1" 


"deg": { 
"$1": 300 


I 
"clouds": ( 
"all": { 
"$1": 5 
} 
E 
"weather": { 
"id": { 
"$1": 800 
}, 
"main": { 
"$1": "Clear" 
}, 


"description": { 


"$1": "Sky is Clear" 


icon": { 
"$1": "02d" 
} 
} 
Lt 
"id": { 
"$1": 3988392 


"name": { 
"$1": "Rosarito" 
Jo 
"coord": { 
"lon": { 
"$1": "-117.033333" 
}, 
"Lat" : { 
"$1": "32.333328" 


"main": { 
"@temp": "82.47", 
"Qpressure": 1012, 
"@humidity": 61, 
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"Qtemp min": "78.8", 
"@temp_max": 86 


}, 
"dt": { 
"$1": 1442170905 
}, 
"wind": { 
"speed": { 
"$15: "4,5" 
}, 
"deg": { 
"$1": 240 
} 
}, 
"clouds": { 
"all": ( 
"$1": 32 
} 
}, 
"weather": { 
"id": { 
"$1": 802 
}, 
"main": { 
"$1": "Clouds" 
}, 
"description": { 
"$1": "scattered clouds" 
}, 
"icon": { 
"$1": "03d" 
} 
} 
}] 


Badgerfish 的 核心 规则 包括 以 下 几 点 。 


。 XML 元 素 名 会 成 为 JSON 对 象 的 属性 名 。 
* XML 元 素 的 文本 内 容 会 成 为 相应 ISON 对 象 的 $ 属性 值 。 例 如 ，<name>Rancho Palos 
Verdes«/name» 会 转换 为 "name": { "$1": "Rancho Palos Verdes" }, 


。 内 艇 元 素 会 成 为 对 象 的 内 艇 属性 。 例 如 ， 以 下 XML: 








«wind» 
«speed»4.1«/speed» 
«deg»300«/deg» 

</wind> 

会 转换 为 

"wind": ( 

"speed": { 
"$1" : "A. g” 
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Js 
"deg": { 
"$1": 300 
} 
} 


。 如 果 同 一 层级 中 存在 多 个 名 称 相 同 的 元 素 ， 则 这 些 元 素 会 转换 为 数组 元 素 。 以 下 XML: 
«city» 
«[city» 
«city» 
«[city» 
会 转换 为 
"city":[ { ... } ] 
* XML 元 素 的 属性 会 转换 为 以 @ 符号 开头 的 对 象 字段 名 。 例 如 ， 以 下 XML: 


«main temp="84.02" pressure="1012" humidity="58" 
temp_min="78.8" temp_max="91"/> 


会 转换 为 


"main": { 
"Qtemp": "84.34", 
"@pressure": 1012, 
"@humidity": 58, 
"@temp_min": "78.8", 
"@temp_max": 93 


} 
以 上 描述 忽略 了 很 多 细节 。 事 实 上 ，Badgerfish 提供 了 非常 优秀 的 文档 资源 。 如 需 了 解 更 
多 信息 ， 可 参考 : 
。 Badgerfish 官方 网 站 ， 
。 Badgerfish 文档 ， 
。 Badgerfish 在 线 测 试 器 。 
2. Parker 
Parker 提供 的 转换 方法 非常 简单 ， 但 它 直 接 忽略 了 XML 属性 ， 因 此 使 用 Parker 将 XML 
转换 为 ISON 会 损失 属性 信息 。 根 据 输入 的 XML， 采用 Parker 得 到 的 JSON 转换 结果 如 例 
7-15 所 示 。 





























例 7-15 data/cities-weather-short-parker.json 
{ 


"cities": [{ 
"id": 5386035, 
"name": "Rancho Palos Verdes", 
"coord": ( 
"lon": -118.387016, 
"lat": 33.744461 
}, 


"main": null, 
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"dt": 1442171078, 

"wind": { 
"speed": 4.1, 
"deg": 300 


"clouds": ( 
"all": 5 
Ts 
"weather": [{ 
"id": 800, 
"main": "Clear", 
"description": "Sky is Clear", 
"icon": "02d" 
H 
Lt 
"id": 5392528, 
"name": "San Pedro", 
"coord": ( 
"lon": -118.29229, 
"lat": 33.735851 
]， 
"main": null, 
"dt": 1442171080, 


"wind": { 
"speed": 4.1, 
"deg": 300 

}, 

"clouds": { 
"all": 5 

Fs 

"weather": [{ 
"id": 800, 


"main": "Clear", 
"description": "Sky is Clear", 
"icon": "02d" 
)] 
t 
"id": 3988392, 
"name": "Rosarito", 
"coord": ( 
"lon": -117.033333, 
"lat": 32.333328 
J 
"main": null, 
"dt": 1442170905, 
"wind": { 
"speed": 4.6, 
"deg": 240 
Ts 
"clouds": ( 
"all": 32 
}, 
"weather": [{ 
"id": 802, 
"main": "Clouds", 
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"description": "scattered clouds", 
"icon": "03d" 
H 
H 
} 


Parker 的 核心 规则 包括 以 下 几 点 。 


* XML 元 素 名 会 成 为 JSON 对 象 的 属性 名 。 
。 忽略 属性 。 

。 内 骸 元 素 转换 为 对 象 的 内 藤 属 ; 
Parker 很 简单 ， 但 存在 以 下 问题 。 


。 转换 过 程 是 有 信息 损耗 的 , 当 使 用 Parker 将 XML 转换 为 JSON 时 , XML 属性 会 被 忽略 。 
。 缺乏 文档 和 工具 支持 。 


7.6.2 ”传统 转换 工具 所 面 对 的 问题 
之 前 列举 的 XML-JSON 相互 转换 工具 存在 以 下 局 限 。 
。 没有 一 个 工具 成 为 公认 的 标准 而 广 为 接 受 。 
。 缺乏 跨 平 台 支 持 和 完整 实现 。 
。 很 多 工具 文档 不 全 。 
。 有 些 工具 进行 数据 转换 时 会 损失 信息 (Parker), 
。 有 些 工具 进行 数据 转换 时 会 改变 数据 结构 (Badgerfish) 。 


7.6.3 XML-JSON 相 互 转换 一 一 总 结 概要 

了 解 了 这 些 传统 转换 工具 的 缺点 后 ， 我 建议 在 进行 以 下 转换 时 避免 使 用 上 述 工 具 。 

TE XML 转换 为 JSON 
在 当前 编程 平台 上 ， 使 用 知名 类 库 将 XML 解析 为 对 象 /Hash (我 们 将 在 Node.js 示例 中 
使 用 xmL2js)。 然 后 使 用 ISON.stringify() (如 果 使 用 的 是 JavaScript) 将 该 对 象 /Hash 
转换 为 JSON。 第 3 章 和 第 4 章 分 别 展示 了 如 何 将 Ruby 数据 和 Java 数据 转换 为 JSON. 


Ff JSON 转换 为 XML 
在 当前 编程 平台 上 ， 使 用 常用 的 类 库 将 JSON 解析 为 相应 的 数据 结构 。 对 于 JavaScript 
KUL, ISON.parse() 就 足够 了 。 第 3 章 和 第 4 章 分 别 展示 了 如 何 将 ISON 解析 为 Ruby 
和 Java 数据 。 然 后 根据 该 数据 结构 来 生成 XML 文档 (该 过 程 称 为 marshaling)。 在 后 
面 基 于 Node.js 的 Mocha/Chai 单元 测试 中 ， 我 们 依旧 使 用 xml2js 来 完成 这 一 操作 。 

不 要 纠结 于 具体 的 转换 工具 / 风格， 应 当 关注 以 下 重点 。 

。 选择 最 有 利于 自己 目标 的 方案 。 

。 使 用 已 经 熟悉 且 上 手 的 类 库 。 

。 测试 转换 结果 ， 确 保 没 有 损失 任何 数据 。 

。 保持 简洁 。 





"E, 

































































JSON 转 换 | 193 





。 封装 所 有 的 转换 操作 ， 并 确保 其 与 目前 的 企业 级 应 用 程序 架构 兼容 。 
简 而 言 之 ， 选 择 当前 编程 平台 中 最 好 的 类 库 ， 然 后 修复 或 绕 过 其 缺陷 。 
解析 /生成 XML 类 库 
XML 已 经 存在 很 长 一 段 时 间 了 ， 主流 平台 上 也 都 有 可 靠 的 解决 方案 ， 如 下 所 示 。 
Node.js 

我 们 将 使 用 xm12js。 
Ruby 

Ruby 中 有 不 少 不 错 的 类 库 


Java 


在 Java 社区 中 ，Java Architecture for XML Binding 多 年 来 一 直 是 相关 领域 的 主要 选择 。 


7.6.4 JSON-XML 相 互 转换 一 一 单元 测试 


例 7-16 中 的 单元 测试 套件 对 “将 JSON 转换 为 XML” 与 “将 XML 转换 为 JSON” 进 行 了 
测试 ， 其 中 用 到 了 以 下 技术 。 


xmL2js 
可 以 使 用 xmL2js 在 XML 和 JavaScript 数据 结构 之 间 进 行 相互 转换 ， 相 关 详 情 可 参考 其 
GitHub 主页 。 




















最 好 的 两 个 是 LibXml 和 Nokogiri。 














JSON.parse()/JSON.stringify() 
二 者 可 用 于 在 JSON 和 JavaScript 数据 结构 之 间 进 行 相 互 转换 。 如 需 了 解 更 多 有 关 
JSON.parse()/JSON.stringify() 的 信息 ， 可 参考 MDN 以 及 第 3 章 中 的 相关 内 容 。 


f 7-16  cities-weather-transform-test/test/json-xml-spec.js 
'use strict'; 





声明 : 城市 天 气 数据 由 0penWeatherMap API 通 过 
Creative Commons Share A Like 许 可 证 发 布 。 
为 兼容 json-server ， 数 据 经 过 了 一 S 
此 操作 并 不 意味 着 得 到 了 许可 方 的 背 


此 代码 通过 Creative Commons Share A Like 许 可 证 发 布 。 
































*/ 


var expect = require('chai').expect; 
var jsonfile = require('jsonfile'); 
var fs = require('fs'); 

var xml2js = require('xml2js'); 


describe('json-xml', function() { 
var jsonCitiesFileName - null; 
var xmlCitiesFileName - null; 


beforeEach(function() { 
var baseDir =  dirname + '/../..'; 





jsonCitiesFileName = baseDir + '/data/cities-weather-short.json'; 
xmlCitiesFileName = baseDir + 
'[data/cities-weather-short.xml'; 


p); 


it('should transform cities JSON data to XML', function(done) { 
jsonfile.readFile(jsonCitiesFileName, function(readJsonFileError, 
json0bj) { 
if (!readJsonFileError) { 
var builder = new xml2js.Builder(); 
var xml = builder .buildObject(json0bj); 
console. Log('\n\n\nXML Output:\n' + xml); 
done(); 
} else { 
done(readJsonFileError); 
} 
IDE 
D 


it('should transform cities XML data to JSON', function(done) { 
fs.readFile(xmlCitiesFileName, 'utf8', function( 
readXmlFileError, xmlData) { 
if (!readXmlFileError) { 
var parser - new xml2js.Parser(); 


parser.parseString(xmlData, function(error, xmlObj) { 
if (!error) { 
console. log('\n\n\nJSON Output:\n' + 
JSON.stringify(xmlObj, null, 2)); 


done() ; 
} else { 
done(error); 


这 段 代码 的 工作 机 制 如 下 。 


。 beforeEach() 会 在 每 个 单元 测试 用 例 运 行 前 先 执 行 ， 并 完成 测试 所 需 的 配置 工作 。 在 本 
例 中 ， 该 方法 会 拼接 生成 输入 的 ISON 文件 和 输出 的 XML 文件 的 文件 名 。 
e 在 'should transform cities JSON data to XML' 单元 测试 用 例 中 : 
— jsonfile.readFile() 读 取 输 入 的 JSON 文 件 , 并 将 其 解析 为 JavaScript 对 象 (json0bj); 
一 xml2js.Builder() 创建 并 返回 一 个 对 象 ， 该 对 象 可 将 ISON 转换 为 XML 
— builder.buildObject(jsonObj) 将 从 JSON 文件 中 读 取 的 JavaScript 对 象 转 换 为 XML 
TR. 
e 在 'should transform cities XML data to JSON' 单元 测试 用 例 中 : 
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一 fs.readFile() 读 取 XML 文件 ， 并 将 结果 存储 在 字符 串 中 ; 

一 xml2js.Parser() 创建 并 返回 一 个 XML 解析 器 

— parser.parseString() 将 从 XML 文件 中 读 取 的 XML 字符 串 转 换 为 JavaScript 对 象 
(xml0bj) ; 

一 JSON.stringify() 将 xml0bj 这 一 JavaScript 对 象 转换 为 JSON 字符 串 。 


7.7 本章 回顾 


本 章 介绍 了 用 于 执行 以 下 操作 的 一 些 ISON 转换 类 库 。 


。 将 JSON 转换 为 HTML. 
— Mustache 或 者 JSON 都 可 以 很 好 地 实现 这 一 操作 。 
。 将 JSON 转换 为 更 加 整洁 的 另 一 种 JSON 结构 。 
— 首选 Handlebars, 
。 在 XML 和 JSON 之 间 进 行 相互 转换 。 
— 无 须 考 虑 用 于 XML 和 JSON 相互 转换 的 传统 转换 工具 。 
- 使 用 在 当前 平台 上 运行 良好 的 XML 类 库 。 
。 编写 单元 测试 来 转换 Web API 所 提供 的 ISON 文档 内 容 。 


这 些 ISON 转换 技术 可 以 将 外 部 API 所 提供 的 JSON 数据 转换 成 应 用 程序 所 兼容 的 数据 
格式 。 


De 
7.8 内 容 预 告 
介绍 完 ISON 生态 系统 (Schema、 搜 索 和 转换 ) 后 ， 我 们 将 开始 讲述 本 书 最 后 一 部 分 内 
容 ， 即 JSON 的 企业 级 应 用 。 这 部 分 内 容 包括 以 下 话题 : 


。 超 媒 体 ， 
* MongoDB (NoSQL) ; 
。 Kafka 消息 系统 。 


在 第 8 章 中 ， 我 们 将 探讨 JSON 超 媒体 ， 并 展示 其 与 API 之 间 的 交互 。 
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想象 一 下 用 HTML 来 搭建 一 个 在 浏览 器 中 使 用 的 Web 应 用 程序 。 在 该 应 用 程序 中 ， 你 可 
以 使 用 标准 的 HTML 来 添加 表单 、 超 链接 和 按钮 ， 而 浏览 器 无 须 等 待 自身 版 本 更 新 即 可 这 
染 这 些 新 增 控件 。 在 “远古 时 代 ”， 事 情 并 不 是 这 样 的 。 那 时 ， 如 果 要 发 布 包含 新 功能 的 
服务 器 端 应 用 程序 ， 就 不 得 不 同时 发 布 新 版 客户 端 代码 ， 使 之 与 服务 器 端 匹 配 。 浏 览 器 的 
出 现 改变 了 这 一 做 法 。 

如 今 ， 我 们 生活 在 一 个 “ 富 客 户 端 ” 时 代 ， 这 个 时 代 是 以 人 们 手中 应 用 程序 的 形式 呈现 出 
来 的 。 当 然 ， 我 们 可 以 通过 手机 来 直接 访问 网 页 ， 但 出 于 种 种 原因 ， 用 户 和 企业 都 更 青 
睐 于 拥有 图 标 、 可 直接 在 设备 上 点 击 打 开 的 原生 应 用 程序 。 在 这 种 情况 下 ， 我 们 如 何 才能 
既 拥 抱 原生 应 用 程序 ， 又 保留 浏览 器 式 的 可 配置 化 特性 呢 ? 答案 就 是 超 媒体 。 使 用 超 媒体 
后 ， 我 们 不 仅 可 以 发 送 数 据 ， 还 可 以 发 送 用 户 能 够 对 数据 进行 的 操作 ， 以 及 触发 这 些 操作 
的 条 件 。 

到 目前 为 止 ， 本 书 所 介绍 的 RESTful API 调用 及 相应 的 JSON 响应 都 是 比较 独立 的 ， 彼 此 
间 没 有 任何 关联 。 演 讲 者 数据 AP 返回 的 所 有 ISON 响应 都 包含 了 各 自 对 应 的 演讲 者 数 
据 ， 但 缺乏 与 这 一 数据 相关 的 资源 / 操作 的 任何 信息 。 


超 媒体 可 以 使 得 REST API 引导 其 使 用 者 实现 以 下 功能 。 


。 链接 到 其 他 相关 资源 (如 其 他 API) 。 例 如 ， 会 议 API 的 返回 结果 中 可 以 包含 预订 、 演 
讲 者 或 会 场 API 的 链接 ， 从 而 让 会 议 API 的 使 用 者 获知 更 多 信息 ， 继 而 引发 购 票 操作 。 

。 对 API 返 回 的 数据 进行 语义 化 。 新 增 的 元 数据 文档 化 地 描述 了 ISON 响应 中 的 数据 ， 并 
定义 了 数据 元 素 的 含义 。 

。 对 当前 返回 的 API 资源 ， 定 义 可 以 进行 的 操作 。 比 如 ， 除 增删 改 查 外 ， 演 讲 者 数据 API 
还 可 以 提供 更 多 操作 。 例 如 ， 提 供 批 量 链接 以 指导 演讲 者 熟悉 演讲 申请 流程 ， 使 其 能 成 
功 地 在 会 议 上 进行 演讲 。 
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超 媒体 将 资源 分 组 打包 ， 引 导 资 源 的 使 用 者 进行 一 系列 操作 并 最 后 实现 业务 目标 。 可 以 将 
超 媒体 理解 为 Web 上 的 购物 流程 在 API 上 的 等 价 物 : 网 页 可 以 通过 购物 车 引导 消费 者 完 
成 所 有 的 购物 流程 并 最 终 付款 (幸运 的 话 )。 超 媒体 格式 向 APT 的 使 用 者 提供 了 一 套 标 准 
化 的 解决 方案 ， 以 便 其 能 解读 并 处 理 API 响应 中 超 链 接 的 数据 元 素 。 

本 章 将 对 以 下 知名 的 JSON 超 媒 体格 式 进 行 对 比 : 

。 Siren 

* JSON-LD 

* Collection-JSON 

e json:api 

* HAL 


8.1. 超 媒体 格式 对 比 


我 们 将 使 用 之 前 章节 中 所 提 到 的 演讲 者 数据 来 探讨 超 媒体 格式 。 以 下 是 调用 假想 的 
myconference 演讲 者 数据 API 所 返回 的 结果 : 


GET http://myconference.api.com/speakers/123456 
































{ 
"id": "123456", 
"firstName": "Larson", 
"lastName": "Richard", 
"email": "Larson.richard@myconference.com", 
"tags": [ 
"JavaScript", 
"AngularJs", 
"Yeoman" 
]， 
"age": 39, 
"registered": true 
} 


如 果 需 要 该 演讲 者 所 做 的 一 系列 报告 的 信息 ， 那 么 就 发 起 另 一 个 API 调用 : 


GET http://myconference.api.com/speakers/123456/presentations 


[ 
{ 
"id": "1123", 
"speakerId": "123456", 
"title": "Enterprise Node", 
"abstract": "Many developers just see Node as a way to build web APIs ...", 
"audience": [ 
"Architects", 
"Developers" 
] 
IF 
{ 
"id": "2123", 





A 
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"speakerId": "123456", 
"title": "How to Design and Build Great APIs", 
"abstract": "Companies now leverage APIs as part of their online ...", 
"audience": [ 
"Managers", 
"Architects", 
"Developers" 
] 
} 
] 


接 下 来 ， 我 们 将 介绍 如 何 使 用 多 种 超 媒体 格式 来 表示 演讲 者 和 报告 信息 APL 


8.1.1 定义 关键 词 

在 继续 深入 前 ， 我 们 先 定义 与 REST 相关 的 几 个 关键 词 。 
保存 数据 的 任何 实体 都 是 资源 ， 其 中 包括 对 象 、 文 档 或 服务 (如 股票 报价 服务 ) 等 。 一 
个 资源 可 以 关联 另 一 个 资源 。 资 源 以 拥有 URI 终端 的 形式 存在 。 


表示 
资源 当前 的 状态 ， 以 JSON 或 XML 的 形式 表达 。 


8.1.2 ”关于 超 媒体 的 个 人 看 法 


在 评价 某 项 特定 技术 时 ， 所 有 的 架构 师 和 开发 人 员 都 会 有 自己 的 看 法 。 在 评估 和 比较 所 有 
的 超 媒体 格式 前 ， 我 会 先 介 绍 一 下 自己 对 超 媒体 的 看 法 。 超 媒体 是 一 项 强大 的 技术 ， 可 以 
TE API 返回 的 数据 中 添加 丰富 的 元 数据 信息 ， 但 这 项 技术 同时 也 充满 了 争议。 很 多 人 热爱 
这 项 技术 ,但 也 有 很 多 人 对 此 表示 厌恶 ， 我 的 态度 则 介 于 两 者 之 间 。 


REST 和 超 媒 体 社区 的 很 多 人 认为 ， 在 JSON 消息 体 中 添加 关于 操作 和 语义 定义 的 元 数据 
是 很 有 用 的 。 我 尊重 所 有 人 的 意见 和 看 法 ,但 只 接受 出 于 以 下 原因 而 使 用 外 部 资源 链接 的 
情况 。 


。 如 果 一 开始 就 能 做 好 API 的 文档 工作 ， 那 么 有 关 操 作 和 数据 定义 的 额外 信息 就 写 无 必 
要 了 。 为 什么 每 次 API 调用 所 返回 的 JSON 数据 中 要 包含 动作 和 数据 类 型 信息 ? 这 在 以 
下 场景 中 尤其 显得 混乱 。 

一 OpenApi( 原 名 Swagger) , RAML 和 API Blueprint 都 可 以 在 API 文档 中 提供 这 一 信息 。 
— JSON Schema 可 以 描述 ISON 数据 所 表示 的 数据 类 型 。 

。 超 媒 体 增 加 了 API 返回 的 JSON 消息 体 的 复杂 度 。 当 使 用 功能 丰富 的 超 媒 体格 式 时 ， 不 
得 不 考虑 以 下 缺陷 。 

— 原始 的 消息 数据 被 更 改 了 ， 并 且 难 以 解读 。 本 章 中 介绍 的 绝 大 多 数 超 媒 体格 式 都 会 
对 原始 的 消息 数据 进行 修改 ， 这 增加 了 使 用 者 理解 和 处 理 API 的 难度 。 

— 作为 API 的 提供 者 ， 你 不 得 不 花费 更 多 的 时 间 和 精力 来 解释 API 的 具体 使 用 方法 ， 
这 却 无 法 阻止 API 的 使 用 者 选择 更 简单 的 末代 产品 。 

- 消息 体 过 于 庞大 ， 会 消耗 更 多 的 带宽 。 
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。 在 消息 体 中 包含 其 他 相关 资源 的 链接 是 一 个 很 不 错 的 方案 ， 因 为 在 不 改变 原始 JSON 数 
据 表示 的 情况 下 ， 这 种 链接 方案 可 以 引导 API 的 使 用 者 使 用 整个 API 











8.1.3 Siren 


Siren (Structured Interface for Representing Entities， 实 体 表 示 的 结构 化 接口 ) 是 在 2012 年 
开发 的 ， 设 计 用 于 表示 Web API 所 返回 的 数据 ， 可 与 JSON 和 XML 协同 工作 。 具 体 可 参 
考 其 GitHub 网 站 。Siren Æ IANA 中 的 媒体 类 型 为 appLication/vnd.siren+json。 
Siren 中 的 核心 概念 如 下 。 
可 以 通过 URI 访问 的 资源 称 为 实体 。 实 体 拥有 属性 和 动作 。 
动作 
可 以 在 实体 上 采取 的 行为 。 
链接 
与 其 他 实体 之 间 的 链接 。 
例 8-1 展示 了 以 下 HTTP 请 求 所 返回 的 Siren 格式 的 演讲 者 数据 。 


GET http://myconference.api.com/speakers/123456 
Accept: application/vnd.siren+json 

















例 8-1 data/speaker-siren.json 
{ 
"class": ["speaker"], 
"properties": { 
"id": "123456", 


"firstName": "Larson", 

"lastName": "Richard", 

"email": "Larson.richard@myconference.com", 
"tags": [ 


"JavaScript", 
"AngularJs", 


"Yeoman" 
], 
"age": 39, 
"registered": true 
}; 
"actions": [ 
{ 
"name": "add-presentation", 


"title": "Add Presentation", 
"method": "POST", 
"href": "http://myconference.api.com/speakers/123456/presentations", 


"type": "application/x-www-form-urlencoded", 
"fields": [ 
{ 
"name": "title", 


"type" : "text" 
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}， 


{ 
"name": "abstract", 
"type": "text" 
{ 
"name": "audience", 
"type": "text" 
} 
] 
} 
1, 
"Links": [ 


{ "rel": ["self"], 
"href": "http://myconference.api.com/speakers/123456" 


E 


"rel": ["presentations"], 
"href": "http://myconference.api.com/speakers/123456/presentations" 
} 
] 
} 


在 以 上 示例 中 ，speaker 实体 的 定义 情况 如 下 。 

。 class 声明 了 该 资源 所 属 的 类 (在 本 例 中 ， 这 个 类 为 speaker), 

e properties 是 一 个 保存 资源 表示 的 对 象 。 该 对 象 是 API 响应 中 真正 的 数据 体 。 

。 actions 定义 了 可 以 对 一 个 speaker 采取 的 动作 。 在 本 例 中 ，actions 声明 了 可 以 对 一 个 
speaker 添加 presentation。 

。 links 提供 了 对 self (当前 资源 ) 和 presentation 资源 的 链接 ，presentation 资源 的 
URI 会 返回 该 speaker 的 演讲 列表 。 

在 描述 实体 资源 上 可 采取 的 动作 时 ，Siren 能 够 提供 非常 好 的 元 数据 。Siren 中 也 有 用 于 描 

述 数 据 的 类 (类 型 )， 但 没有 像 JSON-LD 这 样 的 数据 定义 (语义 声明 )。 














8.1.4 JSON-LD 


JSON-LD (JavaScript Object Notation for Linking Data， 链 接 数 据 的 JavaScript 对 象 表示 法 ) 
于 2014 年 成 为 W3C 标准 。JSON-LD 是 一 种 设计 用 于 REST API 的 数据 链接 格式 ， 可 与 
MongoDB, CouchDB 等 NoSQL 数据 库 一 同 使 用 。 如 需 了 解 更 多 信息 ， 可 参考 其 官方 网 站 
和 GitHub 页 面 。JSON-LD 的 媒体 类 型 是 appLication/Ld+json， 文 件 扩展 名 为 .jsonld。 因 
为 是 W3C 标准 ， 所 以 JSON-LD 拥有 活跃 的 社区 和 庞大 的 工作 组 。 


例 8-2 展示 了 以 下 HTTP 请 求 返回 的 JSON-LD 格式 的 演讲 者 数据 。 


GET http://myconference.api.com/speakers/123456 
Accept: application/vnd.ld+json 



































例 8-2  data/speaker.jsonld 
{ 


"@context": { 
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"Qvocab": "http://schema.org/Person", 

"firstName": "givenName", 

"lastName": "familyName", 

"email": "email", 

"tags": "http: //myconference.schema.com/Speaker/tags", 

"age": "age", 

"registered": "http://myconference.schema.com/Speaker /registered" 
Yo 
"@id": "http://myconference.api.com/speakers/123456", 
"id": "123456", 


"firstName": "Larson", 

"lastName": "Richard", 

"email": "larson.richard@myconference.com", 
"tags": [ 


"JavaScript", 
"AngularJs", 
"Yeoman" 


age": 39, 
"registered": true, 


"presentations": "http://myconference.api.com/speakers/123456/presentations 


j 











在 以 上 示例 中 ，@context 对 象 提供 了 演讲 者 数据 的 总 体 上 下 文 信息 。 有 具体 来 说 ， 除 了 列举 
出 数据 字段 ，@context 还 与 Qvocab 一 起 ， 对 组 成 speaker 对 象 的 数据 元 素 进行 了 精确 的 语 





义 定 义 。 以 下 是 一 些 具 体 解释 。 

。 Schema.org 网 站 提供 了 对 年 龄 和 个 体 等 常用 数据 元 素 的 精确 定义 。 

。 Qvocab 将 基本 类 型 设置 为 个 体 ， 然 后 允许 使 用 其 他 字段 (如 tags 或 registered) 
展 该 类 型 ， 以 供 speaker 使 用 。 

。 @id 本 质 上 是 一 个 URI， 表 示 访 问 某 个 特定 speaker 所 用 的 ID。 











来 扩 


值得 注意 的 是 ， 用 于 表示 speaker 的 核心 ISON 并 未 有 所 改变 ， 而 这 也 是 JSON-LD Erat 
BI API 时 的 一 大 卖点 。 这 种 增 量 式 改进 方案 可 以 避免 破坏 已 有 的 API 使 用 ， 进 而 更 容易 逐 
渐 采 纳 JSON-LD。 在 这 一 方案 中 ， 已 有 的 JSON 可 以 保持 原样 ， 开 发 者 则 可 迭代 地 在 API 








数据 中 添加 数据 链接 的 语义 信息 。 








另外 ，http://myconference.schema.com 这 一 网 站 其 实 并 不 存在 。 事 实 上 ， 示 例 中 使 用 该 网 
站 仅仅 只 是 为 了 演示 而 已 。 如 果 需 要 使 用 Schema.org 上 某 个 不 存在 的 定义 ， 那 么 只 要 能 够 


确保 提供 良好 的 文档 ， 就 可 以 直接 在 自己 的 域名 下 创建 相关 定义 。 
例 8-3 展示 了 以 下 HTTP 请 求 所 返回 的 JSON-LD 格式 的 演讲 者 演说 列表 数据 


GET http://myconference.api.com/speakers/123456/presentations 
Accept: application/vnd.ld+json 








o 


例 8-3 data/presentations.jsonld 


"Qcontext": { 
"Qvocab": "http: //myconference.schema.com/", 
"presentations": { 

@type": "eid", 





"id": "id" 5 
"speakerId": "speakerId", 
"title": "title", 
"abstract": "abstract", 
"audience": "audience" 
} 
}, 
"presentations": [ 
{ 
"@id": "http://myconference.api.com/speakers/123456/presentations/1123", 
"id": "1123", 
"speakerId": "123456", 
"title": "Enterprise Node", 
"abstract": "Many developers just see Node as a way to build web APIs or ...", 
"audience": [ 
"Architects", 
"Developers" 


] 


"@id": "http: //myconference.api.com/speakers/123456/presentations/2123", 
"id": "2123", 
"speakerId": "123456", 
"title": "How to Design and Build Great APIs", 
"abstract": "Companies now leverage APIs as part of their online strategy ...", 
"audience": [ 
"Managers", 
"Architects", 
"Developers" 
] 
} 
] 
} 


在 以 上 示例 中 ，@context 表示 所 有 的 数据 都 与 presentations HEA AK. Al” http:// 
myconference.schema.com/presentations 对 象 不 存在 ， 所 以 我 们 需要 显 式 声明 presentations, 
ange http://myconference.schema.com/presentations 对 象 真 的 存在 ， 则 @context 如 下 所 示 : 




















"Qcontext": "http://myconference.schema.com/presentations" 


你 也 可 以 在 JSON-LD Playground 上 测试 一 下 前 面 的 示例 。JSON-LD Playground 是 一 个 用 
于 校 验 JSON-LD 文档 的 非常 不 错 的 在 线 测 试 工具 。 在 编写 API 代码 前 ， 可 以 使 用 该 工具 
来 校 验 数 据 格式 。 

JSON-LD 本 身 既 不 提供 有 关 操 作 的 信息 ， 也 不 提供 有 关 数 据 表示 的 语义 。 作 为 JSON-LD 
的 插件 ，HYDRA 可 以 为 客户 端 一 服务 器 端 通信 提供 更 多 的 描述 词汇 。 

如 需 了 解 更 多 有 关 HYDRA 的 信息 ， 可 参考 以 下 资源 : 

。 HYDRA 官方 网 站 ， 

。 W3C 社区 。 

例 8-4 展示 了 增加 HYDRA 操作 的 JSON-LD 格式 的 演讲 者 演说 列表 数据 。 


GET http://myconference.api.com/speakers/123456/presentations 
Accept: application/vnd.ld+json 
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例 8-4 data/presentations-operations.jsonld 


{ 


"@context": [ 
"http: //www.w3.org/ns/hydra/core", { 


} 
], 


"Qvocab": "http://myconference.schema.com/", 
"presentations": { 

"@type": "eid", 

"id": "id", 

"speakerId": "speakerId", 

"title": "title", 

"abstract": "abstract", 

"audience": "audience" 


} 


"presentations": [ 


{ 


"@id": "http://myconference.api.com/speakers/123456/presentations/1123", 
"id": "1123", 

"speakerId": "123456", 

"title": "Enterprise Node", 


"abstract": "Many developers just see Node as a way to build web APIs or ... 


"audience": [ 
"Architects", 
"Developers" 


] 


Lt 


j 
IF 


"Qid": "http://myconference.api.com/speakers/123456/presentations/2123", 
"id": "2123", 

"speakerId": "123456", 

"title": "How to Design and Build Great APIs", 


"abstract": "Companies now leverage APIs as part of their online strategy ... 


"audience": [ 
"Managers", 
"Architects", 
"Developers" 


] 


"operation": ( 
"Qtype": "AddPresentation", 
"method": "POST", 
"expects": ( 


"Qid": "http://schema.org/id", 
"supportedProperty": [ 
{ 
"property": "title", 
"range": "Text" 
^t 
"property": "abstract", 
"range": "Text" 


" 
’ 


" 
E 





在 以 上 示例 中 : 

e operation 声明 可 以 通过 POST 请 求 增加 演说 实体 ， 

e Qcontext 引用 了 HYDRA 域 ， 从 而 在 格式 中 添加 operation 关键 词 ， 

。 @vocab 添加 了 http://myconference.schema.com/ 域 和 presentations 定义 。 


由 于 可 以 在 不 改变 原始 数据 的 情况 下 添加 其 他 相关 资源 的 链接 ，JSON-LD 本 身 就 是 一 个 非 


常 优秀 的 工具 。 换 而 言 之 ， 对 API 的 使 用 者 来 说 ， 使 用 JSON-LD 不 会 产生 任何 破坏 性 的 
变更 。 出 于 简洁 性 的 考虑 ， 不 建议 使 用 JSON-LD 时 引入 HYDRA. 











8.1.5 Collection+JSON 


Collection+JSON 创建 于 2011 年 ， 专 注 于 处 理 集合 中 的 数据 成 员 ， 类 似 于 Atom 这 种 订阅 / 
供稿 格式 。 如 需 了 解 更 多 相关 信息 ， 可 参见 Collection+JSON 的 官方 网 站 和 GitHub 主页 。 
Collection+JSON 的 媒体 类 型 为 application/vnd.collection+json, 

合法 的 Collection+JSON 响应 必须 拥有 一 个 名 为 collection 的 根 字段 ， 该 字段 值 为 包含 以 
下 内 容 的 对 象 。 

。 版 本 号 (version)。 

。 值 为 URI 的 href, 该 URI 指 向 self 资源 (请 求 的 原始 资源 )。 

例 8-5 展示 了 以 下 HTTP 请 求 返回 的 Collection+JSON 格式 的 演讲 者 数据 。 


GET http://myconference.api.com/speakers/123456 
Accept: application/vnd.collection+json 























例 8-5  data/speaker-collection-json-links.json 


{ 
"collection": { 
"version": "1.0", 
"href": "http://myconference.api.com/speakers", 
"items": [ 
"href": "http://myconference.api.com/speakers/123456", 
"data": [ 
{ "name": "id", "value": "123456" }, 
{ "name": "firstName", "value": "Larson" }, 
{ "name": "LastName", "value": "Richard" }, 
{ "name": "email", "value": "Larson.richard@myconference.com" }, 
{ "name": "age", "value": "39" }, 
{ "name": "registered", "value": "true" } 
l 
"links": [ 
{ 
"rel": "presentations", 
"href": "http://myconference.api.com/speakers/123456/presentations", 
"prompt": "presentations" 
] 
} 
] 
} 
} 
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对 于 以 上 示例 ， 需 要 注意 以 下 几 点 。 


* collection 对 象 封 装 了 演讲 者 数据 。 
e items 数组 包含 了 演讲 者 集合 中 的 所 有 对 象 。 因 为 请 求 中 包含 ID ， 所 以 该 集合 中 只 有 一 
个 对 象 。 
。 data 数组 包含 了 组 成 一 个 演讲 者 的 所 有 数据 元 素 的 名 称 - 值 对 。 
。 links 数组 提供 了 演讲 者 相关 资源 的 链接 。 每 个 链接 包含 以 下 内 容 。 
— rel 关键 词 对 资源 关系 进行 描述 。 
— href 提供 了 当前 演讲 者 的 presentations 资源 的 超 链接 。 
- HTML 表单 可 以 使 用 prompt 来 引用 演讲 者 集合 。 


Collection+JSON 还 支持 读 取 、 写 入 和 查询 集合 中 的 成 员 ， 但 对 Collection+JSON 的 完整 讨 
论 超出 了 本 书 的 探讨 范围 。 你 可 以 参考 http://amundsen.com/media-types/collection/examples/ 
来 获取 更 多 示例 ， 也 可 以 参考 http://amundsen.com/media-types/tutorials/collection/tutorial-01. 
html 来 学 习 相关 教程 。 

Collection+JSON 在 提供 资源 的 链接 关系 方面 做 了 非常 不 错 的 工作 ， 但 通过 将 数据 转换 为 
data 数组 中 的 名 称 — 值 对 ， 这 一 格式 彻底 改变 了 演讲 者 数据 的 结构 。 









































8.1.6 json:api 
json:api 于 2013 年 开发 ， 用 于 对 API 中 JSON 请 求 / 响 应 的 格式 进行 标准 化 约定 。 虽 然 
json:api 的 主要 关注 点 在 API 请 求 /响应 的 数据 上 ， 但 其 实 它 也 包含 了 超 媒 体 的 部 分 内 容 。 
可 在 其 官方 网 站 和 GitHub 主页 上 了 解 更 多 信息 。json:api 的 媒体 类 型 为 application/vnd. 
api+json。 
一 个 合法 的 json: apt 文档 必须 拥有 以 下 元 素 之 一 作为 根 字 段 。 
data 
资源 的 数据 表示 ， 其 中 包含 一 个 或 多 个 资源 对 象 ， 每 个 资源 对 象 都 必须 拥有 type 字段 
(表示 数据 类 型 ) 和 id 字段 (表示 资源 的 唯一 标识 )。 
errors 
错误 对 象 的 数组 ， 每 个 错误 对 象 包含 调用 API 时 所 得 到 的 错误 码 及 错误 消息 。 
meta 
包含 非 标准 的 元 数据 信息 (如 版 权 、 作 者 等 )。 
可 选 的 根 元 素 如 下 。 
Links 
保存 相关 资源 超 链接 的 对 象 。 
included 
保存 相关 内 置 资源 对 象 的 数组 。 
例 8-6 展示 了 以 下 HTTP 请 求 所 返回 的 json: apt 格式 的 演讲 者 数据 列表 。 


























GET http://myconference.api.com/speakers 
Accept: application/vnd.api+json 


f| 8-6  data/speakers-jsonapi-links.json 
{ 
"Links": { 
"self": "http://myconference.api.com/speakers", 
"next": "http://myconference.api.com/speakers? limit=25&0ffset=25" 


"type": "speakers", 
"id": "123456", 
"attributes": { 
"firstName": "Larson", 
"LastName": "Richard", 
"email": "Larson.richard@myconference.com", 
"tags": [ 
"JavaScript", 
"AngularJS", 
"Yeoman" 


age": 39, 
"registered": true 
} 
}, 
{ 
"type": "speakers", 
"id": "223456", 
"attributes": { 
"firstName": "Ester", 
"lastName": "Clements", 
"email": "ester.clements(myconference.com", 
"tags": [ 
"REST", 
"Ruby on Rails", 
"APIs" 
l 
"age": 29, 
"registered": true 
} 
}, 


n 
} 


以 上 示例 的 工作 机 制 如 下 。 


。 links 数组 提供 了 与 当前 演讲 者 数据 相关 的 资源 的 链接 。 在 本 例 中 ， 每 个 元 素 都 包含 了 
相关 资源 的 URI。 注 意 ， 链 接 的 命名 没有 任何 限制 ， 但 一 般 使 用 self 来 表示 当前 资源 ， 
next 则 往往 用 于 分 页 功能 。 

。 data 数组 中 包含 了 资源 对 象 的 列表 ， 其 中 每 个 对 象 都 拥有 type 字段 (如 speakers) 和 
id 字段 ， 以 满足 json:api 格式 的 要 求 。attributes 对 象 中 保存 了 组 成 每 个 speaker 对 
象 的 名 称 - 值 对 。 
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例 8-7 展示 了 如 何 使 用 json:api RKA AK speaker 资源 的 所 有 presentation WR, 


GET http://myconference.api.com/speakers/123456 
Accept: application/vnd.api+json 


例 8-7 data/speaker-jsonapi-embed-presentations.json 


"links": { 
"self": "http://myconference.api.com/speakers/123456" 


"type": "speaker", 
"id": "123456", 
"attributes": { 
"firstName": "Larson", 
"lastName": "Richard", 
"email": "Larson.richard@myconference.com", 
"tags": [ 
"JavaScript", 
"AngularJs", 
"Yeoman" 


"registered": true 
} 
} 
]， 
"included": [ 
{ 
"type": "presentations", 
"id": "1123", 
"speakerId": "123456", 
"title": "Enterprise Node", 


"abstract": "Many developers just see Node as a way to build web APIs or ... 


"audience": [ 
"Architects", 
"Developers" 
] 
Lt 
"type": "presentations", 
"id": "2123", 
"speakerId": "123456", 
"title": "How to Design and Build Great APIs", 
"abstract": "Companies now leverage APIs as part of their online ...", 
"audience": [ 
"Managers", 
"Architects", 
"Developers" 
] 
} 
] 
} 


" 
5 





在 以 上 示例 中 ，included 数组 (json:api 标准 的 一 部 分 ) FH] T AK presentations 资 
源 。 虽 然 可 以 减少 API 的 调用 次 数 ， 但 这 种 内 艇 资源 的 方式 造成 了 资源 间 的 数据 紧 耦 合 
因为 speaker 资源 必须 知道 presentation 数据 的 格式 和 内 容 。 

例 8-8 通过 Links 提供 了 一 种 更 好 的 方式 来 展现 资源 间 的 关系 。 


GET http://myconference.api.com/speakers/123456 
Accept: application/vnd.api+json 





例 8-8  data/speaker-jsonapi-link-presentations.json 


"links": { 

"self": "http: //myconference.api.com/speakers/123456", 

"presentations": "http://myconference.api.com/speakers/123456/presentations" 
}, 
"data": [ 

{ 


"type": "speaker", 
"id": "123456", 
"attributes": { 


"firstName": "Larson", 

"LastName": "Richard", 

"email": "Larson.richard@myconference.com", 
"tags" : [ 


"JavaScript", 
"AngularJS", 
"Yeoman" 


age": 39, 
"registered": true 
} 
} 
] 
} 


在 以 上 示例 中 ，Links 数组 显示 speaker 拥有 presentations 这 一 资源 ， 同 时 也 提供 了 相 
应 的 URI; 但 这 一 次 speaker 资源 (以 及 相关 API) 并 不 知道 presentation 资源 中 的 具体 
数据 。 另 外 ， 在 此 方案 下 ，API 的 使 用 者 需要 处 理 的 数据 也 更 少 。 这 一 松 耦合 的 设计 使 得 
presentation 数据 可 以 在 不 影响 演讲 者 API 的 情况 下 进行 变更 。 


json:api 中 包含 了 丰富 的 特性 ， 有 具体 包括 标准 化 的 错误 消息 、 分 页 、 内 容 协商 ， 以 及 创建 
/更 新 /删除 资源 的 策略 等 。 我 曾 借用 json:api 标准 中 的 部 分 内 容 来 创建 过 API 规范 。 同 
时 ， 绝 大 多 数 编程 平台 都 能 提供 优秀 的 类 库 来 简化 json:api 的 使 用 。data 数组 及 其 内 部 
资源 对 象 (要 求 具备 type 和 id 字段 ) 会 更 改 原始 的 ISON 数据 表示 ， 其 他 对 象 内 容 则 保 
持 不 变 。 对 json:api 的 完整 讨论 超出 了 本 书 的 探讨 范围 ， 如 需 了 解 更 多 相关 信息 ， 可 访问 
其 示例 网 页 和 完整 的 标准 文档 。 



























































8.1.7 HAL 
HAL (Hypertext Application Language， 超 文本 应 用 程序 语言 ) 于 2012 年 成 为 ETF 标 
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准 ， 设 计 用 于 以 超 链接 的 形式 来 关联 资源 ， 可 与 JSON 和 XML 协同 工作 。 如 需 了 解 更 多 
信息 ， 可 参考 其 官方 网 站 和 GitHub EW., HAL 的 媒体 类 型 为 application/hal+json 和 
application/hal«xml, 


HAL 的 格式 简单 、 可 读 性 强 ， 也 不 会 改变 原始 的 数据 表示 。 作 为 一 种 流行 的 媒体 类 型 ， 
HAL 基于 以 下 两 个 概念 而 设计 。 
资源 对 象 
资源 包含 了 (保存 在 links 对 象 中 的 ) 链接 、 
中 的 内 和 内 资源 (如 订单 资源 中 包含 了 商品 资源 )。 
链接 
链接 提供 了 其 他 外 部 资源 的 URI。 
虽然 embedded 和 _links 对 象 都 是 可 选 的， 但 其 中 之 一 必须 出 现在 合法 HAL 文档 的 对 象 
根 字 段 中 。 
例 8-9 展示 了 以 下 HTTP 请 求 返回 的 HAL 格式 的 演讲 者 数据 。 


GET http://myconference.api.com/speakers/123456 
Accept: application/vnd.hal+json 

















其 他 资源 ， 以 及 保存 在 | embedded 对 象 

















例 8-9  data/speaker-hal.json 


{ 
" links": { 
"self": { 
"href": "http: //myconference.api.com/speakers/123456" 
"presentations": { 
"href": "http://myconference.api.com/speakers/123456/presentations" 
} 
}; 
"id": "123456", 
"firstName": "Larson", 
"LastName": "Richard", 
"email": "Larson.richard@myconference.com", 
"tags": [ 
"JavaScript", 
"AngularJs", 
"Yeoman" 
]， 
"age": 39, 
"registered": true 
} 


以 上 示例 的 工作 机 制 如 下 。 


。 links 对 象 包含 了 链接 关系 信息 ， 其 中 每 条 信息 都 显示 了 链接 的 具体 语义 。 
href 字段 在 链接 关系 中 是 必 备 的 。href 的 值 必须 是 一 个 合法 的 URI (参考 RFC 
3986) 或 URI 模板 (参考 RFC 6570)。 

。 有 关 链 接 关系 的 具体 描述 如 下 。 
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一 self 为 当前 speaker 资源 的 链接 。 

— presentations 为 当前 speaker 将 要 演说 的 资源 。 在 本 例 中 ，presentations 对 象 通过 
href 描述 当前 资源 和 http://myconference.api.com/speakers/123456/presentations 
超 链 接 之 间 的 关系 。 

- 注意 , next 和 find 不 是 HAL 的 关键 词 。HAL 人 允许 使 用 自 定义 名 称 来 描述 链接 对 和 象 。 


接 下 来 我 们 获取 演讲 者 列表 ， 从 而 使 得 以 上 示例 变 得 更 有 意思 ， 如 例 8-10 所 示 。 


GET http://myconference.api.com/speakers 
Accept: application/vnd.hal+json 








例 8-10 — data/speakers-hal-links.json 


{ 
" links": ( 
"self": ( 
"href": "http://myconference.api.com/speakers" 
}, 
"next": { 
"href": "http: //myconference.api.com/speakers? limit=25&0ffset=25" 
}, 
"find": { 
"href": "http: //myconference.api.com/speakers{?id}", "templated": true 
} 
Fa 
"speakers": [ 
{ 
"id": "123456", 
"firstName": "Larson", 
"LastName": "Richard", 
"email": "larson.richard@myconference.com", 
"tags": [ 
"JavaScript", 
"AngularJs", 
"Yeoman" 
]， 
"age": 39, 
"registered": true 
}, 
{ 
"id": "223456", 
"firstName": "Ester", 
"LastName": "Clements", 
"email": "ester.clements@myconference.com", 
"tags": [ 
"REST", 
"Ruby on Rails", 
"APIs" 
]， 
"age": 29, 
"registered": true 
}, 
] 
} 
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以 上 示例 的 工作 机 制 如 下 。 


。 除了 seLf， 还 包括 以 下 链接 关系 。 

— next 声明 了 接 下 来 的 一 批 speaker 资源 。 换 而 言 之 ， 这 是 API 提供 分 页 功能 的 一 
种 方式 。 在 本 例 中 ，Limit 参数 表示 每 次 API 调用 都 会 返回 25 个 speaker 对 象 ， 
offset 参数 则 表示 列表 中 首 个 对 象 为 第 26 个 speaker。 这 一 约定 与 Facebook 的 分 页 
风格 比较 像 。 

一 find 以 模板 链接 的 形式 提供 用 于 搜索 单个 speaker 的 超 链接 。 模 板 中 的 (id) 表示 
可 以 在 URI 中 通过 id 来 搜索 speaker, templated 属性 则 表示 当前 链接 是 一 个 模板 
链接 。 

。 原始 的 ISON 数据 表示 保持 不 变 。 
回 到 第 一 个 示例 ， 我 们 将 所 有 的 presentation MEuKA speaker 资源 ， 如 例 8-11 所 示 。 


GET http://myconference.api.com/speakers/123456 
Accept: application/vnd.hal+json 
































例 8-11 /data/speaker-hal-embed-presentations.json 


{ 
" links": ( 
"self": { 
"href": "http://myconference.api.com/speakers/123456" 
]， 
"presentations": { 
"href": "http://myconference.api.com/speakers/123456/presentations" 
} 
J 
"_embedded": { 
"presentations": [ 
{ 
" links": ( 
"self": ( 
"href": "http://myconference.api.com/speakers/123456/presentations/1123" 
} 
}, 
"id": "1123", 
"title": "Enterprise Node", 
"abstract": "Many developers just see Node as a way to build web APIs ...", 
"audience": [ 
"Architects", 
"Developers" 
] 
}, 
{ 
" links": ( 
"self": { 
"href": "http://myconference.api.com/speakers/123456/presentations/2123" 
} 
Hh 
"id": "2123", 
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"title": "How to Design and Build Great APIs", 
"abstract": "Companies now leverage APIs as part of their online ...", 
"audience": [ 
"Managers", 
"Architects", 
"Developers" 
] 
} 
] 
}， 
"id": "123456", 
"firstName": "Larson", 
"lastName": "Richard", 
"email": "Larson.richard@myconference.com", 
"tags": [ 
"JavaScript", 
"AngularJS", 
"Yeoman" 
]， 
"age": 39, 
"registered": true 


} 


在 以 上 示例 中 ， 相 较 于 使 用 presentations 链接 关系 ， 我 们 使 用 了 embedded 对 象 将 
presentation XFA EKE speaker 中 。 每 个 presentation 对 象 都 拥有 包含 相关 资源 的 _links 
THR. 


乍 一 看 ， 内 嵌 相 关 资 源 的 这 种 做 法 还 挺 合理 ， 但 出 于 以 下 原因 ， 我 更 喜欢 使 用 之 前 的 资源 

链接 的 方案 。 

。 内 岁 资 源 的 方案 增加 了 消息 体 的 规模 。 

。 _embedded 对 象 更 改 了 数据 表示 。 

。 FRAT SERRA TIUS. API 和 演说 API。 使 用 该 方案 后 ， 演 讲 者 API 必须 知道 演说 资源 
的 数据 结构 。 如 果 使 用 资源 链接 方案 ,那么 演讲 者 API 只 需要 知道 相关 API 的 存在 即 可 。 

人 刨 除 内 上航 资产 方案 ，HAL 是 一 种 轻 量 级 的 格式 ， 可 以 在 不 更 改 原始 的 数据 表示 的 情况 下 提 

供 其 他 资源 的 链接 。 


8.2 ”结论 

以 下 是 有 关 超 媒体 的 总 结 : 保持 简单 。 保 持原 始 资源 数据 的 结构 不 变 。 如 果 将 提供 稳定 、 
可 靠 的 API 文档 作为 设计 流程 的 一 个 步 又 ， 那 么 这 一 步 又 本 身 就 已 经 满足 了 很 大 一 部 分 对 
超 媒体 技术 需求 的 初衷 。 对 我 而 言 ， 超 媒体 最 有 用 的 部 分 在 于 和 其 他 资源 的 链接 。“ 彻 底 
超 媒体 化 ”的 支持 者 可 能 会 强烈 反对 我 的 观点 〈 没 关系 ) ， 以 下 则 是 我 的 反驳 。 

。 用 户 不 会 使 用 难以 理解 的 API。 

。 原始 的 JSON 数据 是 最 重要 的 。 不 能 仅仅 为 了 遵循 超 媒 体格 式 就 更 改 资源 的 结构 。 
基于 这 些 考虑 ， 我 选择 最 小 化 的 HAL 结构 〈 仅 包含 链接 ， 不 包含 内 艇 资源 ) 作为 超 媒 体 
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格式 。 即 使 存在 以 上 顾虑 ，HAL 依旧 是 一 种 优秀 的 格式 ， 因 为 它 : 





。 是 可 以 工作 的 最 简单 方案 ; 
» 是 一 项 标准 ; 

。 拥有 广泛 的 社区 支持 ; 
。 拥有 可 靠 的 跨 平台 类 库 ，; 
。 不 改变 原始 的 ISON 数据 表示 ; 
。 对 数据 的 语义 和 操作 没有 要 求 ， 
。 只 做 必需 的 工作 ， 不 会 画蛇添足 。 








json:api 是 我 的 第 二 选择 〈 使 用 资源 链接 而 非 内 藤 资 源 )， 原 因 在 于 : 除 提供 超 媒 体 功 能 





Sh, json:api 还 可 以 对 JSON 请 求 / 响 应 进行 标准 化 ， 同 时 依旧 保持 原始 ISON 数据 的 完 
整 性 与 设计 意图 。 在 对 JSON 数据 有 所 更 改 的 超 媒体 格式 中 ，json:api 算是 影响 最 小 的 。 
因为 json:api 具备 广泛 的 跨 平台 支持 ， 所 以 你 可 以 使 用 编程 类 库 来 减少 格式 化 所 需 的 工 
作 ， 缩 短 并 简化 开发 过 程 。 如 果 在 超 媒 体格 式 外 还 需要 对 整个 企业 内 所 有 API 中 的 ISON 
请 求 /响应 进行 标准 化 (有关 API 设计 的 话题 超出 了 本 书 的 探讨 范围 )， 那 么 json:api 方 











案 是 值得 着 重 考 虑 的 。 























(HJER HYDRA HJ) JSON-LD 是 我 的 第 三 选择 ， 因 为 其 简洁 ， 而 且 不 更 改 原始 的 ISON 数 


据 表 示 。 虽 然 在 已 有 的 API 上 添加 数据 语义 并 不 难 

















E， 但 我 认为 没有 必要 这 么 做 ， 在 定义 数 








据 的 语义 与 结构 这 一 点 上 ， 高 质量 的 API 文档 +JSON Schema 这 样 的 方案 会 更 好 一 些 。 





8.3 建议 


你 可 能 不 赞同 我 对 超 媒 体 的 看 法 ， 但 想象 一 下 ， 如 果 你 作为 一 名 架构 师 或 团队 负责 人 向 整 
个 团队 发 出 “在 开发 API 时 彻底 使 用 超 媒 体 的 全 部 特性 ”这 样 的 指令 ， 那 么 团队 中 的 开发 











人 员 会 将 超 媒 体 视 作 有 益 的 技术 补充 ， 还 是 累 资 ? 











回想 一 下 刚 提出 极限 编程 思想 的 那些 岁 








月 吧 ， 采 用 可 以 工作 的 最 简 方案 。 使 用 正确 的 工具 和 技术 来 完成 工作 ， 同 时 建议 采取 以 下 


策略 。 


。 使 用 OpenApi/Swagger 或 RAML 对 API 进行 文档 化 。 


。 使 用 JSON Schema 来 定义 数据 结构 。 








。 选择 HAL, json:api 或 JSON-LD 作为 超 媒体 格式 ， 并 从 关联 其 他 资源 的 简单 链接 开始 





做 起 。 
。 如 何 评估 开发 流程 的 状态 。 
— 团队 的 开发 速度 如 何 ? 
— API 的 可 测试 性 如 何 ? 
。 向 API 的 使 用 者 寻求 反馈 。 反 馈 内 容 如 下 。 
- 数据 表示 是 否 容易 理解 ? 
— 数据 是 否 容易 读 取 和 使 用 ? 
。 尽早 进行 快速 迭代 和 评估 。 
































使 用 上 述 策略 后 再 分 析 是 否 有 必要 在 ISON 中 添加 操作 和 数据 定义 ， 答 案 很 可 能 是 否定 的 。 





8.4 实际 中 遇 到 的 问题 

如 果 考 虑 在 API 中 使 用 超 媒体 技术 ， 则 最 好 事先 思考 以 下 几 个 问题 。 

。 超 媒体 在 社区 中 的 理解 度 不 高 。 当 我 就 相关 话题 进行 分 享 时 ， 很 多 开发 者 根本 就 疫 听 说 
过 超 媒体 ， 或 者 知之 甚 少 ， 而 且 对 超 媒 体 的 具体 作用 也 是 茫然 无 知 。 即 使 是 最 简单 的 超 
媒体 格式 ， 也 需要 一 些 社区 教育 工作 来 普及 。 

。 标准 缺失 。 超 媒体 格式 有 很 多 种 ， 本 章 介 绍 了 5 种 最 主流 的 ， 其 中 只 有 2 种 (HAL 和 
JSON-LD) 是 拥有 相关 标准 的 。 由 此 可 见 ， 技 术 社区 在 超 媒体 上 的 意见 并 不 一 致 。 

。 对 于 API 的 提供 者 和 使 用 者 来 说 ， 无 论 何 种 格式 ， 超 媒体 的 使 用 都 会 引入 额外 的 序列 
化 / 反 序 列 化 工作 。 因 此 ， 需 要 确保 采用 广 为 接 受 的 超 媒体 格式 ， 以 获得 跨 平 台 的 类 库 
支持 。 这 么 做 可 以 使 得 开发 人 员 的 工作 变 得 更 加 简单 。 在 后 文 使 用 HAL 进行 测试 时 ， 
我 们 将 介绍 相关 内 容 。 


mha x Ht 2-3 
8.5 在 演讲 者 数据 API 中 用 HAL 进 行 测试 
与 之 前 的 章节 相同 ， 我 们 将 在 不 编写 任何 代码 的 情况 下 ， 对 提供 ISON 响应 的 模拟 API 进 
行 测试 。 
8.5.1 测试 数据 
我 们 将 使 用 之 前 章节 中 所 提 到 的 演讲 者 数据 作为 测试 数据 (可 在 GitHub 上 找到 相关 信 
息 )， 并 将 其 部 署 为 RESTful API， 以 创建 模拟 的 测试 API。 同 样 ， 我 们 依旧 使 用 json- 


server 这 一 Node.js 模块 将 speakers.json 文件 暴露 为 Web API。 如 需 安装 json-server， 可 
参考 A.2.5 市 中 的 内 容 。 


可 在 本 机 中 以 5000 端口 运行 json-server: 


cd chapter-8/data 



























































json-server -p 5000 ./speakers-hal-server-next-rel.json 


在 Postman 中 访问 http://localhost:5000/speakers, WFE GET 作为 HTTP 方法 ， 然 后 点 击 Send 
按钮 。 应 该 可 以 观察 到 模拟 API 所 提供 的 所 有 演讲 者 信息 ， 如 图 8-1 所 示 。 
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No Environment 
http://localhost:5000/ 


GET http://localhost:5000/speakers/ Params Send x Save 


Status: 200 OK — Time: 12 ms 


"links": { 
"next": { 
"href": "http://myconference.api . com?limit-25&offset-25" 





": “http://myconference.api.com/speakers{?id}", 
"templated": true 





i7- "tags": [ 

18 "JavaScript", 

19 "AngularJS", 

20 "Yeoman" 

21 1, 

22 "age": 39, 

23 "registered": true 


26 "id": "223456", 

27 "firstName": "Ester", 

28 "lastName": "Clements", 

29 "email": “ester.clements@myconference.com", 





33 "APIs" 











8-1; 在 Postman 中 访问 由 json-server 所 提供 的 HAL 格式 的 演讲 者 数据 
也 可 以 通过 浏览 器 访问 该 URI。 


值得 注意 的 是 ， 在 这 一 示例 中 ， 我 们 必须 向 json-server 传递 演讲 者 数据 文件 信息 ， 才 能 
成 功 启动 服务 器 。 例 8-12 展示 了 更 新 后 的 HAL 格式 结构 。 


例 8-12  data/speakers-hal-server-next-rel.json 
{ 


"speakers": { 

" links": { 

"self": ( 
"href": "http://myconference.api.com/speakers" 


"next": { 
"href": "http://myconference.api.com?limit-25&offset-25" 
}, 
"find": { 
"href": "http: //myconference.api.com/speakers{?id}", 
"templated": true 
} 
}, 
"speakers": [{ 
"id": "123456", 
"firstName": "Larson", 
"lastName": "Richard", 
"email": "Larson.richard@myconference.com", 
"tags": [ 
"JavaScript", 
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"AngularJs", 


"Yeoman" 
]， 
"age": 39, 
"registered": true 
Lt 
"id": "223456", 
"firstName": "Ester", 
"lastName": "Clements", 
"email": "ester.clements@myconference.com", 
"tags": [ 
"REST", 
"Ruby on Rails", 
"APIs" 
]， 
"age": 29, 
"registered": true 
}] 
} 


} 


在 该 示例 中 ， 最 外 面 的 speakers 对 象 结构 是 必需 的 ， 它 使 得 json-server 根据 URI (http:// 
localhost:5000/speakers) 自动 提供 相应 的 文件 ， 剩 余 的 数据 结构 (Links 对 象 和 speakers 
数组 ) 则 保持 不 变 。 


8.5.2 ”HAL 单元 测试 
准备 好 API 后 ， 我 们 将 介绍 单元 测试 的 创建 。 与 之 前 的 章节 相同 ， 我 们 将 继续 使 用 Node.js 
中 的 Mocha/Chai。 继 续 阅 读 前 ， 确 保 已 经 成 功 设置 好 了 测试 环境 。 如 尚未 安装 Node.js, 
可 参考 A.2 节 和 A.2.5 节 中 的 内 容 。 如 需 依照 本 节 的 描述 运行 代码 示例 中 的 项 目 ， 可 使 用 
cd 命令 切换 到 chapter-8/myconference 目录 ， 并 执行 以 下 命令 来 安装 项 目 依赖 ; 

npm install 


如 需 手 动 创 建 本 节 中 的 Node.js 项 目 ， 可 参考 本 书 在 GitHub 上 的 相关 指导 步骤 。 
以 下 是 本 节 单 元 测试 中 使 用 到 的 npm 模块 。 





























Unirest 
我 们 在 之 前 的 章节 中 使 用 该 模块 来 发 起 RESTful API 调用 。 
halfred 


可 从 https://www.npmjs.com/package/halfred 下 载 的 HAL 解析 器 ， 其 GitHub 主 页 为 
https:/github.comy/traverson/halfred 。 


例 8-13 展示 了 如 何 校 验 模拟 演讲 者 数据 API 所 提供 的 HAL 响应 。 
例 8-13  speakers-hal-test/test/hal-spec.js 


'use strict'; 


var expect = require('chai').expect; 
var unirest - require('unirest'); 
var halfred - require('halfred'); 
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describe('speakers-hal', function() { 


p; 


var req; 


beforeEach(function() { 
halfred.enableValidation(); 
req = unirest.get('http://localhost:5000/speakers') 


.header('Accept', 'application/json'); 


it('should return a 200 response', function(done) { 
req.end(function(res) { 


expect(res.statusCode).to.eql(200); 
expect(res.headers[ 'content-type']).to.eql( 

'application/json; charset=utf-8'); 
done(); 


})s 


it('should return a valid HAL response validated by halfred', 
done) { 
req.end(function(res) { 


var speakersHALResponse = res.body; 


halfred.parse(speakersHALResponse) ; 
resource. speakers; 
null; 


var resource 
var speakers 
var speaker1 


console. log('\nValidation Issues: '); 

console. Log(resource.validationIssues()); 
expect(resource.validationIssues()).to.be.empty; 
console. Log(resource) ; 
expect(speakers).to.not.be.null; 
expect(speakers).to.not.be.empty; 

speaker1 = speakers[0]; 
expect(speaker1.firstName).to.not.be.null; 
expect(speaker1.firstName).to.eql('Larson'); 
done(); 


5; 


该 单元 测试 的 运行 机 制 如 下 。 





。 beforeEach() 函数 在 每 个 








function( 


单元 测试 用 例 运 行 前 执行 一 次 ， 并 完成 以 下 操作 。 


— 调用 halfred.enableValidation() 来 配置 halfred 类 库 ， 以 启用 HAL 校 验 功能 。 
— 调用 http://localhost:5000/speakers 这 一 URI 上 的 模拟 API. 
'should return a 200 response' 这 一 测试 用 例 确 保 了 模拟 API 可 以 成 功 返 回 HTTP et 





主要 的 测试 工作 ， 有 具体 如 下 。 
一 调用 halfred.parse() 来 解析 模拟 API 所 返回 的 HAL 响应 。 





HAL 链接 和 剩余 ISON 消息 体 的 halfred Response 对 象 。 如 需 
Z5 halfred 文档 。 


这 一 测试 用 例 中 包含 


'should return a valid HAL response validated by halfred' 这 


该 调用 返回 一 个 包含 
了 解 更 多 信息 ， 可 参 





一 调用 resource.validationIssues() 来 校 验 HAL 响应 ， 并 使 用 chai 检查 校 验 结果 。 在 











接 下 来 使 用 非法 数据 运行 的 单元 测试 中 ， 我 们 将 再 次 看 到 这 一 调用 的 实际 使 用 情况 
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— 使 用 chai 确保 halfred 的 Response 对 象 中 依旧 包含 了 原始 的 speakers 数组 信息 。 


使 用 npm test 来 运行 单元 测试 ， 因 为 模拟 API 所 提供 的 数据 是 合法 的 ， 所 以 单元 测试 会 成 
功 通 过 。 运 行 后 可 以 观察 到 以 下 结果 : 


> mocha test 





























speakers-hal 
w 


Validation Issues: 


Resource { 

_Links: { self: [ [Object] J], next: [ [Object] ], find: [ [Object] ] }, 

-curiesMap: {}, 

_curies: [, 

-resolvedCuriesMap: {}, 

_embedded: {}, 

-validation: [], 

speakers: 

[ { id: '123456', 
firstName: 'Larson', 
lastName: 'Richard', 
email: 'larson.richardémyconference.com' , 
tags: [Object], 
age: 39, 
registered: true }, 

{ id: '223456', 

firstName: 'Ester', 
lastName: 'Clements', 
email: ‘ester.clements@myconference.com' , 
tags: [Object], 
age: 29, 
registered: true } ], 

-original : 

{ _links: { self: [Object], next: [Object], find: [Object] }, 

speakers: [ [Object], [Object] ] } } 
4 


2 passing 


介绍 了 如 何 校 验 HAL 数据 后 ， 我 们 将 修改 由 模拟 API 所 提供 的 数据 ， 使 其 返回 非法 的 结 
果 。 我 们 在 links 对 象 中 删除 了 self 链接 ， 如 例 8-14 所 示 。 


例 8-14  data/speakers-hal-server-next-rel-invalid.json 


























{ 
"speakers": { 
" links": { 
"next": { 
"href": "http: //myconference.api.com?limit-25&offset-25" 
} 
"find": { 
"href": "http://myconference.api.com/speakers{?id}", 
"templated": true 
} 
}, 
} 
} 





你 可 能 还 记得 ，HAL 标准 要 求 Links 对 象 中 必须 包含 setf 引用 。 使 用 以 下 命令 重启 
json-server， 使 其 提供 非法 的 HAL 数据 : 
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cd chapter-8/data 


json-server -p 5000 ./speakers-hal-server-next-rel-invalid. json 


重新 运行 单元 测试 ， 可 以 看 到 halfred 捕获 了 HAL 校 验 中 出 现 的 问题 ， 且 该 测试 也 以 失败 





HAE. 


nx: 


» mocha test 


speakers-hal 
/ 


Validation Issues: 
[ { path: '$. links', 
message: 'Resource does not have a self 


1 passing 


link' } J 


1) speakers-hal should return a valid HAL response validated by halfred: 


Test failed. See above for more details. 


8.6 在 服务 器 端 使 用 HAL 


至 此 ， 我 们 通过 单元 测试 介绍 了 如 何在 客户 端 中 使 用 HAL， 与 此 同时 ， 服 务 器 端 部 署 的 却 
是 模拟 数据 (使 用 了 json-server 和 遵循 HAL 标准 的 静态 ISON 文件 )。 为 了 专注 于 介绍 
JSON， 本 书 在 服务 器 端的 内 容 方 面 着 墨 不 多 。 以 下 是 使 得 RESTful API 返回 HAL 响应 的 














一 些 服务 器 端 类 库 。 


Java 














Spring 的 HATEOS 对 Java 中 基于 Spring 的 RESTful API 提供 了 HAL 支持 。 可 以 在 Spring 


文档 中 找到 高 质量 的 教程 。 
Ruby on Rails 


roar gem 在 Ruby on Rails 中 提供 HAL 支持 。 





JavaScript/NodeJS 





express-hal 对 基于 Express 的 NodeJS RESTful API 提供 HAL 支持 。 
无 论 开 发 平台 是 哪个 、 所 选 的 超 媒体 格式 是 哪 种 ， 在 将 其 选 定 为 最 终 方 案 前 ， 需 要 确保 进 

















行 一 次 快速 实现 以 测试 该 类 库 。 确 保 所 使 月 
非常 重要 的 。 





的 类 库 易 月 











性 强 且 不 会 对 已 有 产品 造成 阻 得 是 
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8.7 ”深入 学 习 超 媒体 
本 章 只 是 介绍 了 超 媒 体 技术 的 一 些 皮 毛 。 如 需 深 入 学 习 ， 可 参考 以 下 资源 : 


* Leonard Richardson 所 著 的 《RESTful Web APIs 中 文 版 》; 
。 Jim Webber 所 著 的 REST in practice: Hypermedia and Systems Architecture(O' Reilly 出 版 社 )。 


8.8 ”本章 回顾 


本 章 通过 以 下 内 容 介 绍 了 如 何在 ISON 中 使 用 超 媒体 
。 比较 一 些 知名 的 JSON 超 媒 体格 式 ， 
。 讨论 在 API 中 添加 超 媒 体 时 的 顾虑 ， 
。 使 用 HAL 来 支持 演讲 者 数据 API 的 测试 。 
A +e 


介绍 了 如 何在 ISON 中 使 用 超 媒体 后 ， 第 9 章 将 展示 ISON 在 MongoDB 中 的 使 用 | 





— 





RL 
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BIS 


JSON5 MongoDB 





MongoDB 是 一 种 NoSQL 数据 库 ， 人 允许 开发 人 员 以 文档 的 形式 存储 数据 。 基 于 文档 的 这 一 
方案 能 够 与 同样 基于 文档 设计 的 JSON 完美 协作 。MongoDB 中 的 数据 模型 是 分 层 结构 的 ， 
对 我 们 在 ISON 文档 中 所 看 到 的 丰富 的 数据 类 型 有 着 良好 的 支持 。 与 ISON 文档 一 样 ， 由 
于 文档 和 对 象 相互 兼容 ，MongoDB 中 的 文档 可 以 很 好 地 与 面向 对 象 编程 平台 进行 整合 ， 
开发 者 也 无 须 使 用 太 多 映射 逻辑 即 可 便捷 地 读 写 数据 库 。 这 一 方案 符合 开发 者 的 直觉 ， 同 
时 也 减轻 了 访问 数据 库 所 需 的 开发 工作 。 

本 章 将 介绍 以 下 操作 : 
。 将 JSON 文档 导入 MongoDB; 

。 在 MongoDB 中 执行 主要 的 几 个 增删 改 查 操作 ; 

。 将 MongoDB 中 的 数据 导出 为 ISON 文档 ， 

。 在 不 编写 代码 的 情况 下 ， 以 模拟 RESTful API 的 形式 访问 MongoDB。 

本 章 专 注 于 介绍 ISON 在 MongoDB 中 的 使 用 情况 ， 并 适当 阐述 数据 库 操作 。 本 章 不 涉及 
使 用 MongoDB 来 开发 应 用 程序 的 相关 内 容 ， 这 些 内 容 足 以 写成 男 外 一 本 书 了 。 如 需 全 面 
了 解 MongoDB 所 提供 的 丰富 功能 ， 推 荐 阅读 Kyle Banker 所 著 的 《MongoDB 实战 (第 二 
版 )》。 


9.1 关于 BSON 


你 可 能 在 MongoDB 的 文档 中 看 到 过 二 进 制 JSON (Binary JSON，BSON) 这 样 的 词汇 。 
BSON 是 MongoDB 内 部 用 于 序列 化 ISON 文档 的 一 种 二 进 制 数据 格式 。 更 多 相关 细节 参 
考 如 下 : 
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e BSON 标准 ; 
。 MongoDB 官方 网 站 。 


可 以 使 用 BSON 向 JSON 文档 中 添加 更 加 丰富 的 数据 类 型 。 
但 考虑 到 本 章 的 目的 : 


。 你 只 需要 了 解 JSON， 即 可 访问 数据 库 ， 
。 JSON 是 MongoDB 向 外 暴露 的 接口 ，BSON 则 只 在 MongoDB 内 部 使 用 。 


9.2 ”安装 MongoDB 


在 继续 深入 前 ， 我 们 先 安装 MongoDB。 相 关 操 作 可 参考 A.4 节 中 的 内 容 。 准 备 好 MongoDB 
后 即 可 构建 并 运行 本 章 中 的 示例 。 


9.3 ”MongoDB 服 务 器 及 相关 工具 


MongoDB 由 以 下 部 件 组 成 。 

。 MongoDB 服务 器 ， 妈 mongod。 

。 用 JavaScript 编写 的 命令 行 。 

。 数据 库 驱 动 ， 该 部 件 使 得 开发 人 员 能 够 在 自己 的 编程 平台 上 访问 MongoDB。 作 为 
MongoDB 的 创始 公司 ，10gen 支持 很 多 编程 语言 ， 具 体 包 括 : Java, Ruby, JavaScript, 
Node.js, C++ 和 C#/.Net 等 。 关 于 官方 支持 的 驱动 列表 ， 可 访问 MongoDB 网 站 。 

， 命令 行 工具 ， 

一 mongodump 和 mongorestore 工具 提供 备份 和 恢复 功能 。 

一 mongoexport 和 mongoimport 工具 提供 MongoDB 的 数据 导入 /导出 功能 ， 支 持 的 数据 
类 型 包括 CSV、TSV 和 JSON。 

一 mongostat 用 于 监听 数据 库 性 能 (如 连接 数 、 内 存 使 用 情况 等 )。 


9.4 MongoDB 服 务 器 


mongod 进程 与 其 他 数据 库 服 务 器 类 似 ， 能 接受 连接 并 处 理 对 数据 的 增删 查 改 操作 。 可 以 在 
macOS 和 Linux 的 命令 行 中 启动 mongod; 
























































mongod & 


如 果 MongoDB 安装 正确 ， 则 初始 启动 中 的 日 志 会 显示 如 下 : 


2016-06-29T11:05:37.960-0600 I CONTROL [initandlisten] MongoDB starting : pid... 
2016-06-29T11:05:37.961-0600 I CONTROL [initandlisten] db version v3.2.4 
2016-06-29T11:05:37.961-0600 I CONTROL [initandlisten] git version: e2ee9ffcf... 
2016-06-29T11:05:37.961-0600 I CONTROL [initandlisten] allocator: system 
2016-06-29T11:05:37.961-0600 I CONTROL [initandlisten] modules: none 
2016-06-29T11:05:37.961-0600 I CONTROL [initandlisten] build environment: 
2016-06-29T11:05:37.961-0600 I CONTROL [initandlisten] distarch: x86 64 
2016-06-29T11:05:37.961-0600 I CONTROL [initandlisten] target arch: x86 64 
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2016-06-29T11:05:37.961-0600 
2016-06-29T11:05:37.962-0600 
2016-06-29T11:05:37.963-0600 
2016-06-29T11:05:37.973-0600 
2016-06-29T11:05:37.973-0600 
2016-06-29T11:05:37.973-0600 
2016-06-29T11:05:37.973-0600 I JOURNAL [initandlisten 
2016-06-29T11:05:37.973-0600 I JOURNAL [initandlisten 


I CONTROL [initandlisten 
I 
W 
I 
I 
I 
I 
I 
2016-06-29T11:05:37.974-0600 I JOURNAL [initandlisten 
I 
I 
I 
I 
I 
I 
I 
I 
I 


- [initandlisten 
- [initandlisten 
JOURNAL [initandlisten 
JOURNAL [initandlisten 
JOURNAL [initandlisten 


options: { config: "/u... 
Detected data files in... 
Detected unclean shutd... 
journal dir=/usr/local... 
recover begin 

info no lsn file in jo... 
recover lsn: 0 

recover /usr/local/var... 
recover applying initi... 
2016-06-29T11:05:37.976-0600 I JOURNAL [initandlisten] recover cleaning up 
2016-06-29T11:05:37.976-0600 I JOURNAL [initandlisten] removeJournalFiles 
2016-06-29T11:05:37.977-0600 I JOURNAL [initandlisten] recover done 
2016-06-29T11:05:37.996-0600 I JOURNAL [durability] Durability thread started 
2016-06-29T11:05:37.996-0600 I JOURNAL [journal writer] Journal writer thread... 
2016-06-29T11:05:38.329-0600 I NETWORK [HostnameCanonicalizationWorker] Start... 
2016-06-29T11:05:38.330-0600 I FTDC [initandlisten] Initializing full-time... 
2016-06-29T11:05:38.330-0600 I NETWORK [initandlisten] waiting for connection... 
2016-06-29T11:05:39.023-0600 I FTDC [ftdc] Unclean full-time diagnostic da... 


从 外 部 看 ，MongoDB 会 监听 27017 端口 ， 但 你 可 以 通过 以 下 选项 更 改 该 端口 号 
mongod --port <your-port-number> 
可 以 在 命令 行 中 输入 以 下 命令 来 关闭 服务 器 : 

kill <pid> 


该 命令 中 的 «pid» 表示 mongod 进程 中 的 进程 DD 号 (Process ID，PID)。 切 记 ， 不 要 使 用 
Kill -9 来 执行 关闭 操作 ， 因 为 这 么 做 会 损坏 数据 库 。 


9.5 将 JSON 导 入 MongoDB 


我 们 已 经 成 功 运 行 了 MongoDB 服务 器 ， 接 下 来 会 将 演讲 者 数据 导入 数据 库 。 使 用 
mongoimport 工具 将 speakers.json 文件 上 传 到 MongoDB。 虽 然 我 们 一 直 在 使 用 这 些 演 讲 者 
数据 ， 但 现在 需要 剥离 数据 的 最 外 层 文档 结构 以 及 speakers 数组 名 : 


{ 

















"speakers": [ 
] 
} 


调整 后 的 speakers.json 文件 如 例 9-1 所 示 。 


例 9-1 speakers.json 


[ 
{ 
"fullName": "Larson Richard", 
"tags": [ 
"JavaScript", 
"AngularJs", 
"Yeoman" 


l, 
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"age": 39, 
"registered": true 
t 
"fullName": "Ester Clements", 
"tags": [ 
"REST", 
"Ruby on Rails", 
"APIs" 


"age": 29, 
"registered": true 
ht 
"fullName": "Christensen Fisher", 
"tags": [ 
"Java", 
"Spring", 
"Maven", 
"REST" 


"age": 45, 
"registered": false 
} 
] 


因为 我 们 并 不 希望 将 JSON 文件 的 内 容 以 整个 文档 的 形式 插入 数据 库 ， 所 以 这 一 调整 是 完 
全 有 必要 的 。 如 果 不 进 行 这 样 的 调整 ， 则 导入 结果 将 会 是 数据 库 中 插入 了 单个 的 speakers 
数组 文档 。 相 反 ， 我 们 需要 的 是 speaker 文档 所 组 成 的 集合 ， 且 集合 中 的 每 个 speaker X 
































档 与 输入 文件 中 的 speaker 对 象 一 一 对 应 。 
在 命令 行 中 执行 nongoimport 后 可 以 观察 到 以 下 结果 : 


json-at-work => mongoimport --db=jsaw --collection=speakers --upsert --jsonArray --file=speakers.json 
2016-06-30T10:33:50.202-0600 connected to: localhost 

2016-06-30T10:33:50.207-0600 imported 3 documents 

json-at-work => mongo 

MongoDB shell version: 3.2.4 

connecting to: test 

> Use jsaw 

switched to db jsaw 


> db.speakers. findQ) 
p "$ o T "fullName" : "Larson Richard", "tags" : [ "JavaScript", "AngularJS", 


: 39, "registered" : true } 


"ye 


: ObjectIdC*S77549ee061561f7f9be9726"), "fullName" : "Ester Clements", "tags" : [ "REST", "Ruby on Rails", "APIs 


: 29, "registered" : true } 
0bjectTd("577549ee061561f7f9beg727"， "fullName" : "Christensen Fisher", "tags" : [ "Java", "Spring", 


X EA "age" : 45, "registered" : false } 


a! 


"Maven" , 





在 以 上 示例 中 ， 我 们 用 到 了 以 下 工具 。 


mongoimport 将 speakers JSON 文件 中 的 数据 导入 jsaw 数据 库 的 speakers 集合 。 
mongo 访问 MongoDB, ， 并 选择 speakers 集合 中 的 所 有 文档 。 更 多 细节 信息 可 参考 下 节 


内 容 。 






































K 9-1 展示 了 MongoDB 的 基本 概念 与 关系 型 数据 库 概念 之 间 的 映射 关系 。 
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表 9-1: MongoDB 与 关系 型 数据 库 
MongoDB 关系 型 数据 库 








数据 库 数据 库 实 例 
集合 表 
文档 行 


9.6 MongoDB 命 令 行 


在 MongoDB 中 成 功 写 入 数据 并 运行 后 ， 现 在 是 时 候 访 问 数据 库 并 使 用 演讲 者 数据 了 。 之 
前 示例 中 所 展示 的 mongo 这 一 命令 行 工 具 提 供 了 访问 MongoDB 的 功能 。 可 以 使 用 以 下 方 
式 来 启动 mongo: 




















json-at-work => mongo 
MongoDB shell version: 3.2.4 
connecting to: test 


> 





mongo 默认 连接 的 是 test 数据 库 ， 我 们 将 使 用 另 一 个 名 为 jsaw (英文 版 书 名 JSON at Work 
的 缩写 ) 的 数据 库 来 单独 存放 演讲 者 数据 : 
json-at-work => mongo 


MongoDB shell version: 3.2.4 
connecting to: test 





> use jsaw 
switched to db jsaw 


>I 





use 命令 将 当前 数据 库 切 换 为 jsaw， 切 换 后 执行 的 所 有 命令 都 只 会 影响 jsaw 这 一 个 数据 

库 。 你 可 能 会 好 奇 jsaw 数据 库 是 如 何 创建 的 ， 有 具体 的 创建 方式 有 两 种 。 

。 通过 mongoimport 工具 创建 。 当 执行 导入 操作 时 ，--db=jsaw 和 --collection=speakers 
命令 行 选项 会 创建 jsaw 数据 库 及 其 中 的 speakers 集合 。 

。 通过 mongo 向 集合 中 插入 文档 也 可 以 创建 jsaw 数据 库 。 后 文 将 介绍 相关 操作 。 

可 在 提示 符 中 输入 exit 来 退出 命令 行 。 该 操作 会 结束 MongoDB 的 命令 行 交 互 ， 并 返回 操 

作 系 统 控 制 台 。 


用 mongo 进 行 基本 的 增删 改 查 操作 

了 解 了 mongo 命令 的 一 些 基本 操作 后 ， 接 下 来 我 们 将 使 用 mongo 对 演讲 者 数据 进行 增删 改 
查 操 作 。 在 命令 行 中 使 用 的 MongoDB 查询 语言 是 基于 JavaScript 的 ， 这 有 效 简 化 了 访问 
JSON 文档 的 操作 。 

1. 查询 文档 

以 下 是 获取 speakers 集合 (本 章 前 面 已 经 将 其 导入 MongoDB) 中 的 所 有 文档 的 操作 : 



























































json-at-work => mongo jsaw 

MongoDB shell version: 3.2.4 

connecting to: jsaw 

> db.speakers.findO) 
| 


: 39, "registered" : true } 
ObjectId("577549ee061561f7f9be9726"), "fullName" : "Ester Clements", "tags" : [ "REST", "Ruby on Rails", "APIs" J], "a 
"registered" : true ] 
: ObjectId("577549ee061561f7f9be9727"), "fullName" : "Christensen Fisher", "tags" : [ "Java", "Spring", "Maven", "REST" 
" : 45, "registered" : false } 





有 关 该 命令 (db.speakers.find()) 的 详细 说 明 如 下 。 

。 操作 命令 以 db 开头 。 

。 speakers 是 集合 的 名 称 。 

。 在 没有 任何 查询 参数 的 情况 下 ，find() 会 返回 speakers 集合 中 的 所 有 文档 。 


再 看 一 下 命令 行 执行 的 结果 ， 我 们 可 以 看 到 返回 的 数据 与 JSON 类 似 ， 几 乎 可 以 说 是 一 模 

一 样 。 复 制 执行 结果 ， 并 粘贴 到 JSONLint 中 。 点 击 Validate JSON 按钮 ， 你 会 发 现 id 字 

段 有 误 。 当 mongoimport 命令 导入 JSON 输入 文件 中 的 演讲 者 数据 并 创建 speakers 集合 时 ， 

MongoDB 会 在 每 个 文档 中 插入 id 字段 (用 作 数 据 库 中 的 主键 的 对 象 DD)。 出 于 以 下 原 

因 ，MongoDB 命令 行 中 的 查询 结果 并 不 是 合法 的 JSON, 

。 最 外 面 表示 数组 的 中 括号 ([]) 缺失 。 

e ObjectId(...) 并 不 是 合法 的 JSON 值 。JSON 中 的 合法 标量 值 包括 : 数值 、 布 尔 值 ， 以 
及 用 双 引 号 括 起 来 的 字符 串 。 

。 用 于 分 隔 speaker 文档 的 逗号 缺失 。 

本 章 前 面 介绍 了 如 何 将 合法 的 JSON 导入 MongoDB ， 介 绍 完 剩余 的 增删 改 查 操作 后 ， 我 

们 会 展示 如 何 将 MongoDB 集合 导出 为 合法 的 ISON. 

如 果 只 需要 返回 标签 中 包含 REST 的 演讲 者 ， 可 以 在 find OO) 方法 中 添加 查询 参数 : 
















































































json-at-work => mongo jsaw 
MongoDB shell version: 3.2.4 
connecting to: jsaw 

> db.speakers. find({tags: 'REST']) 


{ "Lid" : ObjectId("577549ee061561f7f9be9726"), "fullName" : "Ester Clements", "tags" : [ "REST", "Ruby on Rails", "APIs" ], "a 
"registered" : true } 
ObjectId("577549ee061561f7f9be9727"), "fullName" : "Christensen Fisher", "tags" : [ "Java", "Spring", "Maven", "REST" 
" : 45, "registered" : false } 




















我 们 在 这 个 示例 中 添加 了 查询 参数 {tags: 'REST'}， 该 参数 使 得 查询 结果 只 返回 tags 数 
组 中 包含 'REST' 值 的 那些 speaker 文档 。MongoDB 查询 语言 是 基于 JavaScript HRF É 
量 语法 设计 的 。 如 需 提 高 有 关 JavaScript 对 象 方面 的 知识 ， 可 参考 David Flanagan MARI 
《JavaScript 权威 指南 (第 6 版 )》。 

可 以 使 用 以 下 命令 来 获取 speakers 集合 中 的 文档 数 


> db.speakers.count() 
3 


2. 创建 文档 
以 下 示例 展示 了 如 何在 speakers 集合 中 添加 新 的 文档 : 
































a 
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json-at-work => mongo jsaw 

MongoDB shell version: 3.2.4 

connecting to: jsaw 

> db.speakers.insert({ 

fullName: 'Carl ClojureDev', 

tags: ['Clojure', 'Functional Programming'], 
age: 45, 

registered: false 


"T 
WriteResult({ "nInserted" : 1 }) 


> db.speakers.findQ 
id" : ObjectId("577549ee061561f7f9be9725"), "fullName" : "Larson Richard", "tags" : [ "JavaScript", "AngularJS", "Yeoman" ] 
9, "registered" : true } 
jectId("577549ee061561f7f9be9726"), "fullName" : "Ester Clements", "tags" : [ "REST", "Ruby on Rails", "APIs" J, "a 
"registered" : true ] 
ObjectId("577549ee061561f7f9be9727"), "fullName" : "Christensen Fisher", "tags" : [ "Java", "Spring", "Maven", "REST" 
45, "registered" : false } 
: ObjectId("577584327a0be85396f1daed"), "fullName" : "Carl ClojureDev", "tags" : [ "Clojure", "Functional Programming" 
" : 45, "registered" : false } 





该 示例 使 用 了 insertO 国 数 ， 在 调用 国 数 时 传人 了 包含 名 称 - 值 对 的 JavaScript 对 象 字面 
量 ， 从 而 创建 了 新 的 speaker 文档 。 


3. 修改 文档 
我 们 的 新 演讲 者 Carl ClojureDev 决定 在 自己 的 技术 擅长 点 上 增加 Scala。 为 了 将 该 编程 语 
言 添 加 到 tags 数组 中 ， 需 要 执行 以 下 操作 : 


json-at-work => mongo jsaw 
MongoDB shell version: 3.2.4 
connecting to: jsaw 
> db.speakers.find({fullName: 'Carl ClojureDev'}) 
{ "Lid" : Object1d("577584327a0be85396f1daed"), "fullName" : "Carl ClojureDev", "tags" : [ "Clojure" ], "age" : 45, "registered 
": false } 
> db.speakers.update({fullName: 'Carl ClojureDev'}, 
+ { $push: 
{ tags: 'Scala' } 














ZR») 
WriteResult({ "nMatched" : 1, "nUpserted" : 0, "nModified" : 1 }) 

> db.speakers.find({fullName: 'Carl ClojureDev'}) 

{ "Lid" : ObjectId("577584327a@be85396fidaed"), "fullName" : "Carl ClojureDev", "tags" : [ "Clojure", "Scala" ], "age" : 45, "r 
egistered" : false } 

> 





该 示例 使 用 了 update() 国 数 ， 具 体 解释 如 下 。 


。 {fullName: 'Carl ClojureDev') 查询 参数 负责 找到 需要 进行 修改 的 那个 speaker 文档 。 
。 Spush 操作 符 在 tags 数组 中 添加 'scata' 。 这 与 JavaScript 中 的 push() 函数 比较 像 。 


值得 注意 的 是 ，update() 函数 中 还 能 使 用 很 多 其 他 的 操作 符 ， 如 $set; 但 $set 会 用 一 个 
全 新 的 值 来 覆盖 目标 字段 ， 因 此 使 用 时 需要 格外 小 心 。 


4. 删除 文档 
最 后 ， 从 集合 中 删除 Carl ClojureDev 这 一 演讲 者 : 


json-at-work => mongo jsaw 
MongoDB shell version: 3.2.4 
connecting to: jsaw 
> db peakers. find({fullName: 'Carl ClojureDev'}) 
F : ObjectIdC" '5775906647776536ff96a2fc"), "fullName" : "Carl ClojureDev", "tags" : [ "Clojure", "Scala", "Functional Prog 
"age" : 45, "registered" : false } 
» db. s remove( {ful Name: "Carl ClojureDev'}) 
WriteResult({ "nRemoved" : 1 }) 
> db.speakers.find({fullName: 'Carl ClojureDev'}) 


























> db.speakers.findQ 
T : ObjectId("577549ee061561f7f9be9725"), "fullName" : "Larson Richard", "tags" : [ "JavaScript", "AngularJS", "Yeoman" ] 
9, "registered" : true } 
: ObjectId("577549ee061561f7f9be9726"), "fullName" : "Ester Clements", "tags" : [ "REST", "Ruby on Rails", "APIs" ], "a 
29, "registered" : true } 
bjectId("577549ee061561f7f9be9727"), "fullName" : "Christensen Fisher", "tags" : [ "Java", "Spring", "Maven", "REST" 
" : 45, "registered" : false } 














在 该 示例 中 ， 我 们 使 用 含有 (fullName: 'Carl ClojureDev'} 参数 的 remove() 函数 来 删除 


特定 文档 。 如 果 之 后 调用 findO 函数 ， 就 可 以 发 现 speakers 集合 中 的 该 文档 确实 已 经 删 


除 ， 其 他 文档 则 不 受 影响 。 


9.7 从 MongoDB 中 导出 JSON 文 档 





了 解 了 MongoDB 服务 器 和 命令 行 的 使 用 后 ， 接 下 来 我 们 介绍 如 何 将 数据 导出 为 合法 的 




















JSON 文档 。 按 照 以 下 方式 使 用 mongoexport 工具 即 可 看 到 相应 结果 : 


json-at-work => mongoexport --db=jsaw --collection=speakers --pretty --jsonArray 


2016-06-30T12:58:32.270-0600 connected to: localhost 


"rids 
"oid": "577549ee061561f7f9be9725" 
}, 
"fullName": "Larson Richard", 
"tags": [ 
"JavaScript", 
"AngularJs", 
"Yeoman" 


age": 39, 
"registered": true 


"ad": { 
"$oid": "577549ee061561f7f9be9726" 
}, 
"fullName": "Ester Clements", 
"tags": [ 
"REST", 
"Ruby on Rails", 
"APIs" 


age": 29, 
"registered": true 


"ad": { 
"$oid": "577549ee061561f7f9be9727" 
}, 
"fullName": "Christensen Fisher", 
"tags": [ 
"Java", 
"Spring", 
"Maven", 
"REST" 


age": 45, 
"registered": false 


3] 


2016-06-30T12:58:32.271-0600 exported 3 records 
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以 上 示例 中 的 mongoexp 
数组 优化 显示 在 标准 输 





ort 命令 读 取 jsaw 数据 库 内 的 speakers 集合 中 的 数据 ， 并 将 JSON 
出 中 。 这 是 一 个 不 错 的 开始 ， 但 为 了 获取 能 在 MongoDB 外 正常 使 


























用 的 合法 JSON， 我 们 还 需要 移 除 结果 中 的 MongoDB 对 象 ID ( id), mongoexport 始终 会 
返回 id， 因 此 我 们 需要 借助 其 他 工具 来 过 滤 id 字段 。 


通过 组 合 使 用 工具 ， 我 们 可 以 获取 最 终 需 要 的 ISON 格式 ， 而 jq 古 满足 这 一 点 的 完美 选 





择 。 你 或 许 还 记得 第 6 











章 中 提 到 过 的 内 容 ，jq 是 一 个 非常 优秀 的 命令 行 工具 ， 除 了 搜索 


JSON， 它 还 提供 了 高 质量 的 ISON 过 让 功能 。jq 不 像 第 7 章 中 提 到 的 Handlebars 那样 具 





备 完整 的 JSON 转换 功 





能 ， 但 也 足够 满足 我 们 的 需求 了 。 通 过 管道 将 mongoexport 命令 的 











结果 输入 ja 以 进行 处 班 





EE ， 我 们 可 以 观察 到 以 下 结果 : 








json-at-work => mongoexport --db-jsaw --collection=speakers --pretty --jsonArray | jq '[.[] | delC. id)]' 
2016-06-30T13:09:56.236-0600 connected to: localhost 
2016-06-30T13:09:56.237-0600 exported 3 records 


{ 


: "Larson Richard", 


"JavaScript", 
"AngularJS", 
"Yeoman" 


: 39, 


: "Ester Clements", 


70 
"REST", 


"Ruby on Rails", 
"APIs" 


: 29, 
: true 


: "Christensen Fisher", 


: [ 
"Java" , 
"Spring", 
"Maven" , 
"REST" 


: false 


json-at-work => || 





最 终结 果 完 全 符合 我 们 的 预期 ， 即 由 不 包含 MongoDB 对 象 ID 的 speaker 对 象 所 组 成 的 合 


ik ISON 数组 。 以 下 是 


对 该 命令 的 详细 解释 。 


。 有 关 mongoexport 命令 的 解释 如 下 。 
一 --db-jsaw --collection-speakers 声明 了 读 取 的 是 jsaw 数据 库 中 的 speakers 集合 。 
一 --pretty --jsonArray 确保 输出 的 是 一 个 优化 显示 的 JSON 数组 。 























。 mongoexport 的 结果 被 导入 标准 输出 ， 随 后 通过 管道 输入 jq。 
。 jq 表 达 式 [.[] | del(._id)] 的 工作 机 制 如 下 。 




















- 最 外 层 的 数组 中 括号 (D) 确保 输入 的 JSON 数组 、 对 象 及 其 字段 在 最 终 输 出 结 


中 保持 不 变 。 
- .[] 声明 ja 会 搜索 整个 数组 。 

















3B 


— 目标 为 del(._id) 命令 的 管道 声明 3a 将 从 输出 中 删除 所 有 的 -id 字段 。 


。 ja 的 结果 被 导入 标准 输出 ， 这 可 以 作为 输入 写 入 文件 。 





该 实际 示例 展示 了 ja 强大 的 功能 。 虽 然 语法 有 些 过 于 精炼 ， 但 ja 还 是 ISON 工具 集中 一 
个 很 不 错 的 选择 。 如 需 了 解 更 多 有 关 ja 的 信息 ， 可 参考 第 6 章 中 的 相关 内 容 。 另 外 ， 也 


可 查阅 jq 手册 。 


9.8 关于 Schema 


MongoDB 是 没有 Schema 的 ， 这 意味 着 数据 库 既 不 会 校 验 数 据 ， 也 不 会 在 存储 数据 时 依赖 
Schema。 然 而 ， 应 用 程序 对 存储 在 每 个 文档 中 的 数据 还 是 会 有 数据 结构 上 的 预期 ， 因 为 只 
有 这 样 ， 应 用 程序 才能 放心 地 使 用 集合 与 文档 。 对 象 文档 映射 (Object Document Mapper, 











ODM) 在 MongoDB 之 上 提供 了 额外 的 特性 : 


。 用 于 校 验 数据 并 强制 使 用 统一 数据 结构 的 Schema; 

。 对 象 建 模 ， 

。 基于 对 象 的 数据 访问 。 

MongoDB 中 不 存在 单个 的 跨 平台 ODM。 相 反 ， 每 个 编程 平台 都 有 





























自己 的 相关 类 库 。 











Node.js 开发 者 一 般 会 使 用 Mongoose。 以 下 是 一 个 简要 的 示例 ， 展 示 了 如 何 声 明 speaker 


的 Schema、 如 何 创建 模型 ， 以 及 如 何 向 数据 库 中 插入 speaker 对 象 。 


var mongoose = require('mongoose' ); 
var Schema = mongoose. Schema; 
mongoose. connect('mongodb: //locaLlhost/jsaw'); 





// 声明 演讲 者 Schema 


var speakerSchema = new Schema({ 
fullName: String, 
tags: [String], 
age: Number, 
registered: Boolean 


DE 
// 创建 演讲 者 模型 
var Speaker = mongoose.model('Speaker', speakerSchema); 


var speaker = new Speaker({ 
fullName: 'Carl ClojureDev', 
tags: ['Clojure', ‘Functional Programming'], 
age: 45, 
registered: false 
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]); 
speaker.save(function (err) { 
if (err) { 
console. Log(err); 
} else { 
console. log('Created Speaker: ' + speaker.fullName); 


} 
p; 


Mongoose 模型 的 实质 是 一 个 基于 Schema 的 构造 器 ， 该 构造 器 封装 了 访问 MongoDB 集合 
的 底层 细节 。Mongoose 文档 则 是 Mongoose 模型 的 一 个 实例 ， 提 供 了 访问 MongoDB 文档 
的 功能 。Mongoose Schema 和 JSON Schema 是 两 个 不 同 的 东西 。Node.js 模块 json-schema- 
to-mongoose 可 以 将 JSON Schema 转换 为 对 应 的 Mongoose Schema， 具 体操 作 就 留 给 你 自 
己 实践 了 。 除 了 创建 文档 ，Mongoose 还 提供 了 操作 文档 的 其 他 功能 : 读 取 (find())、 修 
改 (save() 或 update()) 和 删除 (remove())。 


其 他 编程 平台 也 有 自己 的 访问 MongoDB 的 ODM, 


Java 
Spring 用 户 可 以 使 用 提供 了 POJO 和 MongoDB 映射 的 Spring Data，Hibernate OGM 则 
为 包括 MongoDB 在 内 的 NoSQL 数据 库 提供 了 Java 持久 化 API 支持 。 


Ruby 
可 以 使 用 MongoDB 官方 支持 的 Mongoid。 


9.9 用 MongoDB 进 行 RESTful APRII 


完整 地 介绍 MEAN 技术 栈 超出 了 本 书 的 探讨 范围 ， 这 么 做 的 话 就 偏离 了 本 章 的 主题 ， 并 且 
无 法 专注 于 JSON。 接 下 来 我 们 会 对 MongoDB 进行 不 同 的 操作 ， 将 其 作为 模拟 的 RESTful 
API 来 使 用 。 使 用 模拟 RESTful API 的 优势 是 显著 的 。 


。 无 须 编码 ， 这 将 开发 者 从 开发 、 维 护 基 础 设施 代码 这 样 单 调 沉 问 的 工作 中 解放 出 来 
了 。 这 样 一 来 ， 开发 人 员 就 能 够 专注 于 提供 业务 价值 (API 中 的 业务 逻辑 ) 的 那 部 
分 代码 。 

。 促使 API 开发 团队 在 正式 开始 编码 前 先 创建 一 个 API 的 初始 设计 。 这 一 策略 称 为 “API 
优先 ”设计 。 这 么 做 的 话 ， 因 为 模拟 API 中 没有 任何 实现 ， 开 发 者 只 是 基于 这 一 接口 
进行 后 续 的 设计 ， 所 以 最 终 的 API 就 不 太 会 向 外 暴露 领域 对 象 与 数据 库 中 的 具体 实现 
a. 

。 API 的 使 用 者 无 须 等 待 真正 的 API 完成 即 可 拥有 一 个 可 行 的 模拟 替代 版 本 。 

。 API 的 开发 者 现在 拥有 足够 的 时 间 来 进行 开发 ,无 须 为 了 支持 API 的 使 用 者 而 赶 工 发 布 。 

。 API 的 开发 者 可 以 尽早 从 使 用 者 那儿 收集 有 关 APT. 可 用 性 的 反馈 ， 并 使 用 这 些 信息 来 挝 
代 更 新 设计 与 实现 。 



















































































9.9.1 测试 输入 数据 


我 们 将 继续 使 用 本 章 前 面 所 导入 的 演讲 者 数据 。 


9.9.2 ”对 MongoDB 进 行 RESTful 封 装 


根据 MongoDB 的 文档 ， 有 好 几 个 可 靠 的 REST 接口 工具 以 独立 服务 器 的 形式 运行 在 MongoDB 
之 上 ， 有 具体 如 下 。 


Crest 
基于 Node.js 的 Crest 能 够 提供 完整 的 增删 改 查 操作 (HTTP GET, PUT, POST 和 DELETE), 
可 在 其 GitHub 主页 上 找到 更 多 细节 信息 。 


RESTHeart 
基于 Java 的 RESTHeart 能 够 提供 完整 的 增删 改 查 功能 ， 可 查看 其 主页 了 解 更 多 信息 。 


DrowsyDromedary 
基于 Ruby 的 DrowsyDromedary 能 够 提供 完整 的 增删 改 查 功能 ， 可 在 其 GitHub 主页 上 
查看 更 多 信息 。 


Simple REST API 
MongoDB 默认 提供 该 工具 ， 但 该 工具 只 支持 HTTP GET， 不 提供 完整 的 REST 功能 
(PUT, POST 和 DELETE) 。 如 需 了 解 更 多 信息 ， 可 参考 RESTHeart 网 站 上 的 Simple REST 
API 文 档 。 


为 Crest, RESTHeart 和 DrowsyDromedary 都 支持 主要 的 几 个 HTTP 方法， 能够 处 理 使 
用 者 的 增删 改 查 请 求 ， 所 以 它们 都 可 以 满足 我 们 的 需求 。 考 虑 到 Crest 易于 安装 配置 ， 
此 接 下 来 我 们 将 主要 使 用 Crest, WI BS A.2.5 节 中 的 内 容 来 安装 Crest。 然 后 在 本 机 中 切 
换 到 crest 目录 ， 在 命令 行 中 使 用 node server 来 启动 Crest 服务 器 。 你 应 该 可 以 观察 到 以 
下 结果 : 


node server 




























































































DEBUG: util.js is loaded 
DEBUG: rest.js is loaded 
crest listening at http://:::3500 


然后 打开 浏览 器 并 访问 以 下 URL: http://localhost:3500/jsaw/speakers。 该 访问 请 求 会 使 得 
Crest 对 MongoDB 中 jsaw 数据 库 内 的 speakers 集合 执行 GET 〈 读 取 /搜索 ) 操作 。 访 问 后 
可 看 到 如 图 9-1 所 示 的 结果 。 
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eoo [Ì localhost:3500/jsaw/spea! x 





€ > CG fi [D localhost:3500/jsaw/speakers 





[ 
= 1 
fullName: "Larson Richard", 
- tags: [ 

"JavaScript", 
"AngularJS", 
"Yeoman" 

l; 

age: 39, 

registered: true, 

id: "577549ee061561f7f9be9725" 


fullName: "Ester Clements", 
- tags: [ 
"REST", 
"Ruby on Rails", 
"APIs" 
]; 
age: 29, 
registered: true, 
id: "577549ee061561f7f9be9726" 


fullName: "Christensen Fisher", 
- tags: [ 
"Java", 
"Spring", 
"Maven", 
"REST" 
]; 
age: 45, 
registered: false, 
id: "577549ee061561f7f9be9727" 











9-1: 由 MongoDB/Crest 提供 的 可 在 浏览 器 中 访问 的 演讲 者 数据 


这 是 一 个 不 错 的 开始 ， 但 因为 浏览 器 只 能 发 送 HTTP GET 请 求 ， 所 以 无 法 在 浏览 器 中 进 
行 完整 的 API 测试 。 接 下 来 ,我 们 将 使 用 之 前 章节 中 提 到 的 Postman 来 完整 测试 Crest/ 
MongoDB 提供 的 演讲 者 数据 API。 输 入 URL: http://localhost:3500/jsaw/speakers, x fé 
HTTP 方法 为 ET， 最 后 点 击 Send 按钮 。 应 该 可 以 看 到 如 图 9-2 所 示 的 结果 。 




















eoe 
加 runner impot 总: Builder 
http;//localhost:3500/jsaw/s 
History 
GET http://localhost:3500/jsaw/speakers 
Today Body (12) 
http://localhost:3500/jsaw/speakers 
Pretty JSON 5 
us| 0 
2- 
3 "fullName": "Larson Richard", 
4- "tags": [ 
5 "JavaScript", 
6 "AngularJS", 
? "Yeoman" 
8 > 
9 "age": 39, 
10 "registered": true, 
11 "id": "577549ee061561f7f9be9725" 
i2 3, 
13 ~ 
14 "fullName": "Ester Clements", 
15- "tags": [ 
16 
17 "Ruby on Rails", 
18 "APIs" 
19 ]， 
20 "age": 29 
21 "registered": true, 
22 "id": "577549ee061561f7f9be9726" 
23 y 
24-| í 
25 "fullName": "Christensen Fisher 
26 "tags" 
27 "Java 
28 "Spring 
29 "Maven 
30 "REST' 
31 











图 9-2: 由 MongoDB/Crest 提供 的 可 在 Postman 中 访问 的 演讲 者 数据 














这 与 之 前 在 浏览 器 中 看 到 的 结果 相同 ， 但 这 一 次 我 们 可 以 修改 API 所 提供 的 数据 了 。 接 
下 来 ， 我 们 删除 其 中 一 个 speaker 对 象 。 首 先 ， 复制 其 中 一 个 speaker HRAJ id， 将 其 添 
加 到 URL 中 :http://localhost:3500/jsaw/speakers/id (URL 中 的 id 即 为 刚 复制 的 对 象 ID)。 
然后 在 Postman 中 选择 DELETE 作为 HTTP 方法 ， 并 点 击 Send 按钮 ， 随 后 即 可 观察 到 以 下 
HTTP 响应 : 

















"ok" : 1 
} 


接着 重复 DELETE 前 的 操作 ， 再 一 次 用 GET 访问 http;//localhost:3500/jsaw/speakers, "T LA fifi 
认 Crest 的 确 调用 了 MongoDB 来 删除 选中 的 speaker, 


至 此 ， 在 不 编写 任何 代码 和 搭建 任何 基础 设施 的 情况 下 ， 我 们 拥有 了 一 个 具备 完整 功能 的 
模拟 REST API， 该 API 可 以 访问 MongoDB 数据 库 并 返回 合法 的 ISON 和 输出。 使 用 这 种 风 
格 的 工作 流 来 梳理 API 的 设计 与 测试 吧 ， 你 将 发 现 团队 的 生产 力 会 得 到 巨大 提高 。 


9.10 ”本 章 回顾 


本 章 介绍 了 JSON 5 MongoDB 协作 的 一 些 基 本 知识 ， 具 体 包 括 : 
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。 将 JSON 文档 导入 MongoDB; 

。 在 MongoDB 中 执行 主要 的 几 个 增删 改 查 操作 ， 

年 MongoDB 中 的 数据 导出 为 JSON 文档 ， 

。 在 不 编写 代码 的 情况 下 ， 以 模拟 RESTful API 的 形式 访问 MongoDB。 


9.11 内 容 预 告 


介绍 完 JSON 5 MongoDB 之 间 的 协作 后 ， 我 们 将 转 而 讨论 ISON 企业 级 应 用 中 的 最 后 一 
个 话题 ， 探 讨 JSON 在 Apache Kafka 中 的 使 用 情况 。 





e 
AL 








第 10 章 


用 Kafka 实 现 JSON 消 息 系统 





Apache Kafka 是 一 个 流行 的 分 布 式 可 扩展 的 消息 系统 ， 人 允许 (在 不 同 编程 平台 上 运行 的 ) 
异 构 应 用 程序 以 消息 传递 的 方式 进行 异步 通信 。Kafka 一 开始 是 LinkedIn 工程 团队 开发 出 
来 的 ， 属 于 某 个 主要 产品 架构 调整 的 一 部 分 。 从 大 型 单 体 应 用 程序 转型 为 微服 务 架 构 模 式 
Ja, LinkedIn 公司 创建 了 Kafka， 以 提供 通用 的 可 处 理 大 型 消息 体 的 数据 流 功能 ， 从 而 在 
整个 公司 范围 内 整合 服务 和 应 用 程序 。2011 年 ，LinkedIn 向 Apache 基金 会 开源 了 Kafka。 
如 今 ， 很 多 公司 都 成 功 使 用 Kafka 作为 企业 产品 架构 中 的 消息 平台 中 心 。 如 需 了 解 更 多 有 
X Kafka 的 信息 ， 可 参考 Apache 的 Kafka 主页 。 

Kafka 与 其 他 消息 系统 (Atl Java Message Service, IMS) 的 不 同 之 处 在 于 : Kafka 与 具体 
的 编程 平台 无 关 。 虽 然 Kafka 本 身 是 用 Java 编写 的 ， 但 消息 的 生产 者 和 消费 者 可 以 使 用 
其 他 编程 语言 来 开发 。 为 了 演示 这 一 点 ， 在 本 章 的 端 到 端 示例 中 ， 我 们 会 使 用 Node.js 和 
Bourne Shell 来 编写 消息 的 消费 者 。 

Kafka 既 支 持 二 进 制 消息 ， 也 支持 文本 消息 。 最 受 欢 迎 的 文本 消息 格式 有 : 普通 文本 、 
JSON 和 Apache Avro, Kafka 的 API (消息 的 生产 者 和 消费 者 所 用 的 接口 ) 是 基于 TCP 3t 
行 通信 的 。 本 章 将 Kafka 作为 传统 的 ISON 消息 系统 ， 并 展示 以 下 操作 : 

。 在 命令 行 中 通过 Kafka 来 生产 /使 用 JSON 消息 ， 

。 设计 并 实现 一 个 小 型 的 端 到 端 示 例 ， 并 在 示例 中 使 用 Kafka 与 JSON。 


10.1 Kafka 的 用 例 


典型 的 Kafka 用 例如 下 所 示 。 
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传统 的 消息 系统 
应 用 程序 发 布 其 他 应 用 程序 所 使 用 的 消息 。Kafka 使 用 异步 (发 送 者 无 须 等 待 响 应 结 
AT) 的 发 布 /订阅 模型 来 解 而 消息 的 生产 者 和 消费 者 。 
































分 析 与 流 处 理 
应 用 程序 向 Kafka 的 相关 主题 发 布 实时 的 使 用 信息 (如 鼠标 点 击 、 访 客 信 息 、 会 话 、 
面 访问 和 购买 操作 )。 然 后 ， 像 Apache Spark/Spark Streaming 这 样 的 流 处 里 应 用 程 


可 以 读 取 多 个 主题 的 消息 、 转 换 数据 (通过 map/reduce 等 )， 并 通过 Flume 将 最 终 的 结 
果 发 送 到 Hadoop 这 样 的 数据 仓库 中 。 对 于 目标 数据 仓库 中 的 数据 ， 你 可 以 使 用 各 种 分 
析 工 具 (如 数据 可 视 化 ) 来 处 理 。 
运 维 与 应 用 程序 性 能 监控 
应 用 程序 可 以 发 布 各 种 统计 数据 (如 消息 数 、 事 务 数 、 啊 应 时 间 、HTTP 响应 码 和 
HTTP 请 求 数 等 )， 运 维 人 员 则 可 以 对 此 进行 检查 、 监 控 ， 从 而 追踪 性 能 、 产 品 使 用 和 
潜在 问题 。 
日 志 归 集 
企业 中 的 所 有 应 用 程序 都 可 以 向 某 个 Kafka 主题 发 布 日 志 消 息 ， 然 后 就 可 以 使 用 日 志 
管理 应 用 程序 对 它们 进行 处 理 ， 如 ELK (ElasticSearch, Logstash, Kibana) 技术 栈 。 
Kafka 可 以 部 署 在 Logstash 前 来 接收 海量 数据 ， 并 允许 Logstash 在 不 损失 信息 的 情况 下 
以 自己 的 市 奏 来 执行 那些 性 能 消耗 较 大 的 操作 。 


10.2 ”Kafka 中 的 概念 和 专 有 和 名词 


以 下 是 Kafka 架构 中 的 一 些 关键 概念 。 

生产 者 
负责 向 主题 发 布 消息 。 

消费 者 
注册 、 订 阅 主题 ， 读 取出 现 的 消息 。 

主题 
一 个 命名 的 频道 ， 某 一 类 消息 的 订阅 源 。 在 本 章 的 示例 中 ，new-proposals-recvd 主题 
包含 了 MyConference 中 的 新 演说 提案 的 所 有 消息 。 还 可 以 将 主题 看 作业 务 事 件 所 组 成 
的 流 ， 流 中 包括 了 下 订单 和 退货 等 事件 消息 。 一 个 主题 可 以 分 为 一 个 或 多 个 分 区 。 












































代理 

管理 一 个 或 多 个 主题 的 Kafka 服务 器 
集群 

包含 一 个 或 多 个 代理 。 
分 区 





在 分 布 式 环境 中 ， 一 个 主题 在 多 个 分 区 中 拥有 副本 ， 每 个 副本 都 由 单独 的 代理 所 管理 。 
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偏 移 量 

分 区 中 的 消息 所 独 有 的 ID. Kafka 使 用 偏 移 量 来 维护 消息 的 顺序 。 
了 解 这 些 概念 后 ， 就 可 以 在 本 章 中 进行 ISON 消息 的 生产 和 消费 了 。 为 简洁 起 见 ， 本 书 不 
涉及 Kafka 中 其 他 的 一 些 重要 领域 ， 其 中 包括 : 耐久 性 、 消 费 者 组 、 消 息 传递 保障 和 副本 。 
Kafka 是 一 个 可 以 用 整 本 书 来 讲述 的 大 话题 ， 如 需 了 解 更 多 信息 ， 可 参考 Neha Narkhede 
所 著 的 《Kafka 权威 指南 》'。 


在 本 章 的 示例 中 ， 我 们 会 使 用 单个 代理 (Kafka 服务 器 )， 而 每 个 主题 也 都 只 有 一 个 分 区 。 


10.3 Kafka 生 态 系统 一 一 相关 项 目 


Kafka 是 一 个 通用 的 消息 系统 ， 可 与 其 他 消息 处 理 系统 集成 来 搭建 更 为 强大 的 消息 应 用 程 
序 。Kafka 的 技术 生态 系统 包括 但 不 局 限于 以 下 项 目 。 


Apache Spark/Spark Streaming 
用 于 流 处 理 ( 详 见 10.1715). 



























































HiveKa 
与 Hive 进行 集成 ， 从 而 为 Kafka 的 主题 提供 类 SQL 的 接口 。 
ElasticSearch 
独立 的 消费 者 从 Kafka 的 主题 中 拉 取 数据 ， 然 后 加 载 到 ElasticSearch 中 进行 处 理 。 
Kafka Manager 
Kafka 的 管理 控制 台 ， 可 用 于 管理 Kafka 集群 、 主 题 、 消 费 者 等 。 
Flume 
将 大 量 数据 从 频道 (如 Kafka 主题 ) 迁移 到 Hadoop 分 布 式 文件 系统 中 。 
Avro 


一 种 数据 序列 化 格式 ， 可 以 作为 纯 ISON 格式 的 替代 来 提供 更 丰富 的 数据 结构 。Avro 
不 是 一 项 标准 ， 但 拥有 自己 的 JSON 格式 的 Schema (该 Schema 与 JSON Schema 无 
关 )。 作 为 JSON 的 替代 方案 ，Avro 能 提供 更 丰富 的 数据 结构 和 更 紧凑 的 数据 格式 。 
Avro 一 开始 是 Hadoop 的 一 部 分 ， 但 最 终 成 为 了 一 个 单独 的 项 目 。 
以 上 列举 的 项 目 仅仅 只 是 能 与 Kafka 协作 的 小 部 分 系统 。 有 关 完 整 的 Kafka 生态 系统 的 描 
述 ， 可 参考 Kafka 生态 系统 网 页 。 


10.4 配置 Kafka 环 境 


在 介绍 Kafka 的 命令 行 界面 前 ， 需 要 先 安装 Kafka 和 Apache ZooKeeper 来 构建 并 运行 本 章 
中 的 所 有 示例 。 可 参考 A.8 节 中 的 内 容 来 安装 Kafka 和 ZooKeeper。 












































注 1: 此 书 已 由 人 民 邮 电 出 版 社 出 版 。 一 一 编者 注 
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安装 好 Kafka 后 ， 就 可 以 对 其 进行 配置 ， 以 允许 删除 主题 (该 操作 默认 是 禁用 的 )。 按 以 

下 方式 编辑 KAFKA-INSTALL-DIR/KAFKA. VERSION/libexec/config/server.properties 文件 

(KAFKA-INSTALL-DIR 是 Kafka 的 安装 目录 ，KAFKA_VERSION 则 是 安装 的 Kafka 版 本 ) : 
# 允许 /禁止 主题 删除 的 开关 ， 默 认 值 为 faLse 


delete.topic.enable-true 








为 什么 需要 ZooKeeper 


至 此 ， 你 可 能 会 产生 一 些 困 惑 : 为 什么 除 Kafka 外 还 需要 ZooKeeper YE? 简单 来 说 就 是 
Kafka 需要 ZooKeeper 才能 运行 。 换 而 言 之 ， 作 为 分 布 式 应 用 程序 的 Kafka 就 是 设计 在 
ZooKeeper 环境 中 运行 的 。ZooKeeper 是 一 个 用 于 协调 分 布 式 进 程 的 服务 器 ， 有 具体 根据 以 
下 参数 来 进行 管理 : 命名 、 状 态 信息 、 配 置 、 位 置信 息 、 同 步 状态 、 容 错 转 移 等 ， 其 命名 
注册 表 使 用 了 与 文件 系统 相似 的 层级 化 命名 空间 策略 。 

很 多 知名 项 目 都 使 用 了 ZooKeeper， 其 中 包括 Kafka, Storm, Hadoop, MapReduce, 
HBase 和 Solr ( 云 服务 版 )。 如 需 学 习 更 多 相关 知识 ， 可 访问 ZooKeeper 的 官方 网 站 。 


10.5 “Kafka 命 令 行 界 面 


Kafka 具有 内 置 的 命令 行 界面 ， 这 允许 开发 人 员 对 Kafka 进行 一 些 实验 操作 。 我 们 将 展示 
如 何 启动 Kafka、 如 何 发 布 ISON 消息 ， 以 及 如 何 关闭 Kafka 程序 。 

如 需 使 用 已 经 编写 好 的 脚本 以 避免 大 量 的 手动 输入 ， 可 以 访问 本 书 代码 示例 中 的 
chapter-10/scripts 目录 ， 然 后 更 改 文件 权限 ， 将 所 有 的 脚本 设置 为 可 执行 : 


chmod +x *.sh 


10.5.1 如何 用 命令 行 界面 发 布 JSON 消 息 
以 下 是 启动 Kafka 并 发 布 / 使 用 消息 的 一 系列 步骤 ( 按 操作 顺序 排列 ) 。 


(1) 启动 ZooKeeper。 

(2) 启动 Kafka 服务 器 。 

(3) 创建 主题 。 

(4) 启动 消费 者 程序 。 

(5) 向 主题 发 布 消息 。 

(6) 使 用 该 消息 。 

(7) 清理 并 关闭 Kafka. 
。 关闭 消费 者 程序 。 


















































。 删除 主题 。 
。 关闭 Kafka。 





。 关闭 ZooKeeper。 





242 | 第 10 章 


10.5.2 ”启动 ZooKeeper 





正如 之 前 所 提 到 的 ，Kafka 依赖 ZooKeeper 才能 运行 。 可 以 在 一 个 新 的 命令 


以 下 命令 来 启动 ZooKeeper: 
./start-zookeeper.sh 
例 10-1 展示 了 该 脚本 的 内 容 。 


例 10-1 scripts/start-zookeeper.sh 
zkServer start 


运行 后 可 以 观察 到 以 下 结果 : 


json-at-work => ./start-zookeeper.sh 
ZooKeeper JMX enabled by default 





Using config: /usr/local/etc/zookeeper/zoo.cfg 
Starting zookeeper ... STARTED 





10.5.3 ”启动 Kafka 

接 下 来 ,我们 就 可 以 在 一 个 新 的 命令 行 终端 中 启动 Kafka 服务 器 了 : 
./start-kafka.sh 

该 脚本 的 内 容 如 例 10-2 所 示 。 


例 10-2 scripts/start-kafka.sh 
kafka-server-start /usr/local/etc/kafka/server.properties 











T 


们 之 前 已 经 编辑 过 这 一 文件 。 





行 终端 中 运行 


在 该 脚本 中 ，server. aug 文件 保存 了 有 关 Kafka 的 配置 信息 。 为 了 允许 删除 主题 ， 我 


现在 Kafka 服务 器 应 该 已 经 成 功 运 行 了 。 执 行 这 一 命令 会 打印 很 多 日 志 人 信息， 启动 完成 后 


则 可 以 看 到 以 下 结果 : 


[2016-12-31 16:42:01,371] INFO Creating /brokers/ids/@ (is it secure? false) (kafka.utils.ZKCheckedEphemeral) 
[2016-12-31 16:42:01,375] INFO Result of znode creation is: OK (kafka.utils.ZKCheckedEphemeral) 


[2016-12-31 16:42:01,377] INFO Registered broker @ at path /brokers/ids/0 with addresses: PLAINTEXT -> EndPoint(10.229.1 


04.161,9092,PLAINTEXT) (kafka.utils.ZkUtils) 


[2016-12-31 16:42:01,385] INFO Kafka version : 0.10.1.0 (org.apache.kafka.common.utils.AppInfoParser) 


[2016-12-31 16:42:01,385] INFO Kafka commitId : 3402a74efb23d1d4 (org.apache.kafka.common.utils.AppInfoParser) 





[2016-12-31 16:42:01,386] INFO [Kafka Server 0], started (kafka.server.KafkaServer) 


10.5.4 创建 主题 


ie 我 们 创建 主题 test-proposals-recvd 来 接收 新 的 演讲 提案 。 可 以 通过 在 新 的 命令 


终端 中 运行 以 下 脚本 来 创建 主题 


./create-topic.sh test-proposals-recvd 


该 脚本 会 运行 kafka-topics 命令 ， 如 例 10-3 所 示 。 





用 Kafka 实 现 JSON 消 





息 系统 | 243 


例 10-3 scripts/create-topic.sh 


kafka-topics --zookeeper localhost:2181 --create V 
--topic $1 --partitions 1 V 
--replication-factor 1 


该 脚本 的 工作 机 制 如 下 。 

。 $1 是 命令 行 变 量 ， 用 于 保存 主题 的 名 称 (本 例 中 为 test-proposats-recvd) 。 

。 为 保持 示例 的 简洁 性 ， 对 于 该 主题 ， 我 们 只 使 用 一 个 分 区 (有 序 的 记录 列表 ) 和 一 个 副 
本 。 一 个 分 区 可 以 在 多 个 服务 器 间 进 行 复制 ,从 而 实现 容错 和 人 负载 均衡 。 在 生产 环境 中 ， 
一 般 会 有 多 个 副本 来 支持 大 量 的 消息 数据 。 





























运行 之 前 的 脚本 后 可 以 观察 到 以 下 结果 : 


json-at-work => ./create-topic.sh test-proposals-recvd 





Created topic "test-proposals-recvd". 


10.5.5 ”列举 主题 

运行 以 下 脚本 可 以 确认 已 经 成 功 创建 新 的 主题 : 
./list-topics.sh 

该 脚本 使 用 了 kafka-topics 命令 ， 如 例 10-4 所 示 。 


例 10-4 scripts/list-topics.sh 
kafka-topics --zookeeper LocaLhost:2181 --list 


可 以 看 到 ， 确 实 已 经 创建 test-proposals-recvd 主题 : 








json-at-work => ./list-topics.sh 


— consumer. offsets 
test-proposals-recvd 


— consumer offsets 是 Kafka 内 部 实现 中 的 底层 细节 ， 因 此 无 须 关心 。 我 们 只 需要 关心 刚 
创建 的 主题 。 


10.5.6 ”启动 消费 者 程序 


拥有 主题 后 就 可 以 生产 和 消费 消息 了 。 首 先 ， 我 们 使 用 以 下 脚本 来 创建 一 个 监听 test- 
proposals-recvd 主题 的 消费 者 : 


./start-consumer.sh test-proposals-recvd 


该 脚本 使 用 了 kafka-console-consumer 命令 ， 如 例 10-5 所 示 。 











例 10-5 scripts/start-consumer.sh 


kafka-console-consumer --bootstrap-server localhost:9092 V 
--topic $1 





在 该 脚本 中 ， 作 为 命令 行 变 量 的 $1 保存 了 消费 者 监听 的 主题 名 称 (本 例 中 为 test-proposals- 


recvd), 


可 以 看 到 ， 消 费 者 程序 正在 等 待 新 消息 ， 因 此 屏幕 上 暂时 没有 任何 显示 : 


json-at-work => ./start-consumer.sh test-proposals-recvd 


10.5.7 2 消息 
接 下 来 就 可 以 在 新 的 命令 行 终端 中 使 用 以 下 脚本 针对 我 们 的 主题 来 发 布 JSON 消息 了 : 


./publish-message.sh '{ "message": "This is a test proposal." }' test-proposals- 
recvd 


例 10-6 展示 了 该 脚本 的 内 容 。 
例 10-6 scripts/publish-message.sh 











echo SMESSAGE FROM CLI | kafka-console-producer \ 
--broker-list localhost:9092 V 
--topic $TOPIC NAME FROM CLI 


在 以 上 脚本 中 ， 需 要 注意 以 下 几 点 。 


。 我 们 使 用 echo 命令 将 JSON 消息 打印 到 标准 输出 中 ， 并 通过 管道 将 其 用 作 kafka- 
console-producer 命令 的 输入 。 
e S$MESSAGE_FROM_CLI 是 命令 行 变量 ,保存 了 需要 发 布 的 JSON 消息 


























。 S$TOPIC_NAME_FROM_CLI 是 命令 行 变量 ,保存 了 主题 的 名 称 (本 例 中 为 Ee 
发 布 消息 后 ， 应 该 可 以 观察 到 以 下 结果 : 


json-at-work => ./publish-message.sh '{ "message": "This is a test proposal." }' test-proposals-recvd 














消息 本 身 不 会 在 用 于 发 布 的 命令 行 终端 中 显示 。 


10.5.8 使 用 JSON 消 息 


切换 回 启 动 消费 者 程序 的 命令 行 窗口 ， 你 应 该 可 以 看 到 消费 者 程序 读 取 并 打 儿 了 test- 
proposals-recvd 主题 中 的 消息 : 














json-at-work => ./start-consumer.sh test-proposals-recvd 
{ "message": "This is a test proposal." } 





至 此 ,一 个 用 于 生产 和 消费 ISON 消息 的 简单 Kafka 示例 就 算 完成 了 。 接 下 来 ， 我 们 将 对 
一 示例 进行 清理 扫尾 工作 。 
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10.5.9 清理 并 关闭 Kafka 

以 下 是 清理 和 关闭 Kafka 的 一 系列 步骤 。 

(1) 关闭 消费 者 程序 。 

(2) 删除 主题 (可 选 )。 

(3) 关 闭 Kafka。 

(4) 关闭 ZooKeeper。 

1. 关闭 消费 者 程序 

只 需 在 启动 消费 者 程序 的 命令 行 窗口 中 按 下 Ctrl-C， 即 可 看 到 以 下 结果 : 


json-at-work => ./start-consumer.sh test-proposals-recvd 
{ "message": "This is a test proposal." } 

















ACProcessed a total of 1 messages 


2. 删除 主题 
可 以 使 用 以 下 脚本 来 删除 test-proposals-recvd 主题 (此 步骤 为 可 选 ) : 


./delete-topic.sh test-proposals-recvd 
例 10-7 显示 了 该 脚本 的 内 容 。 
例 10-7  scripts/delete-topic.sh 


kafka-topics --zookeeper localhost:2181 --delete --topic $1 


在 该 脚本 中 ， 作 为 命令 行 变量 的 $1 保存 了 主题 的 名 称 (本 例 中 为 test-proposals-recvd), 
运行 脚本 后 即 可 看 到 以 下 结果 : 


json-at-work => ./delete-topic.sh test-proposals-recvd 
Topic test-proposals-recvd is marked for deletion. 














Note: This will have no impact if delete.topic.enable is not set to true. 


3. 关闭 Kafka 
只 需 在 启动 Kafka 的 命令 行 窗口 中 按 下 Ctrl-C， 即 可 关闭 Kafka, 你 也 可 以 使 用 以 下 命令 
来 优雅 地 执行 关闭 操作 : 


./stop-kafka.sh 
例 10-8 展示 了 该 脚本 的 内 容 。 
例 10-8 scripts/stop-kafka.sh 


kafka-server-stop 


该 脚本 使 用 了 kafka-server-stop 命令 来 关闭 Kafka 服务 器 。 这 一 受 控 的 关闭 操作 需要 一 
定 的 时 间 ， 并 会 打印 出 很 多 日 志 消 息 。 如 果 切 换 回 启动 Kafka 服务 器 的 命令 行 窗口 ， 你 应 
该 可 以 在 命令 行 的 最 后 观察 到 以 下 消息 ， 


























[2016-12-31 18:40:06,981] INFO [GroupCoordinator 0]: Shutdown complete. (kafka.coordinator.GroupCoordinator) 
[2016-12-31 18:40:06,988] INFO Terminate ZkClient event thread. (org.IOItec.zkclient.ZkEventThread) 
[2016-12-31 18:40:06,990] INFO Session: 0x159573c11390007 closed (org.apache.zookeeper.ZooKeeper) 


[2016-12-31 18:40:06,990] INFO EventThread shut down for session: 0x159573c11390007 (org.apache.zookeeper.ClientCnxn) 
[2016-12-31 18:40:06,992] INFO [Kafka Server 0], shut down completed (kafka.server.KafkaServer) 








如 果 在 之 前 的 操作 过 程 中 删除 了 test-proposals-recvd 主题 ， 那 么 重新 启动 Kafka 后 该 主 
题 将 不 复 存 在 。 如 果 并 未 删除 该 主题 ， 则 重新 启动 Kafka 后 仍旧 可 以 对 该 主题 进行 使 用 。 
4. 关闭 ZooKeeper 
我 们 以 关闭 ZooKeeper 来 收尾 。 在 命令 行 中 输入 以 下 命令 : 

./stop-zookeeper .sh 
例 10-9 显示 了 该 脚本 的 内 容 。 


例 10-9 scripts/stop-zookeeper.sh 
zkServer stop 


至 此 ， 有 关 Kafka 的 所 有 程序 都 应 该 已 经 关闭 了 。 你 应 该 可 以 在 命令 行 中 看 到 以 下 结果 : 

















json-at-work => ./stop-zookeeper.sh 
ZooKeeper JMX enabled by default 


Using config: /usr/local/etc/zookeeper/zoo.cfg 
Stopping zookeeper ... STOPPED 





10.6 ”Kafka 的 类 库 
Kafka 在 主流 的 应 用 程序 开发 平台 上 有 着 广泛 支持 ， 具 体 包 括 以 下 类 库 。 














Java 
Spring 在 Java 社区 中 广泛 用 于 系统 集成 ， 并 可 以 通过 Spring Kafka 为 Kafka 提供 支持 。 
Ruby 


可 以 在 GitHub 上 找到 karafka gem, 


JavaScript 
在 接 下 来 的 内 容 中 ， 我 们 将 使 用 kafka-node 模块 来 搭建 端 到 端 示 例 。 如 需 了 解 更 多 有 
X kafka-node 的 信息 ， 可 参考 其 npm 和 GitHub 网 站 。 


10.7 ” 端 到 端 示 例 一 MyConference 中 的 演讲 者 提案 


前 面 的 内 容 已 经 展示 了 如 何在 命令 行 中 使 用 Kafka， 接 下 来 我 们 会 将 其 与 Nodejs 应 用 程序 
进行 集成 ， 从 而 实现 对 消息 的 生产 和 消费 。 对 于 本 章 最 后 的 这 个 示例 ， 我 们 将 创建 一 个 允 
许 演讲 者 向 MyConference (一 家 虚构 的 公司 ) 提交 新 提案 的 应 用 程序 。 每 个 演讲 者 都 会 提 
交 一 个 提案 ， 这 些 提案 会 由 MyConference 提案 团队 的 成 员 审核 。 审 核 后 ， 演 讲 者 就 可 以 
电子 邮件 收 到 有 关 审 核 结果 的 提醒 。 
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通过 


10.7.1 测试 数据 
我 们 将 继续 使 用 之 前 章节 中 所 使 用 的 演讲 者 数据 ， 但 会 添加 一 些 元 素 ， 以 便 提 案 更 加 完 
整 。 例 10-10 展示 了 更 新 后 的 演讲 提案 数据 。 














用 Kafka 实 现 JSON 消 息 系统 | 247 


例 10-10 data/speakerProposal.json 
{ 


"speaker": { 
"firstName": "Larson", 
"LastName": "Richard", 
"email": "Larson.richard@ecratic.com", 
"bio": "Larson Richard is the CTO of ... and he founded a JavaScript meetup ... 
} 
"session": { 
"title": "Enterprise Node", 
"abstract": "Many developers just see Node as a way to build web APIs or ...", 
"type": "How-To", 
"Length": "3 hours" 
J> 
"conference": { 
"name": "Ultimate JavaScript Conference by MyConference", 
"beginDate": "2017-11-06", 
"endDate": "2017-11-10" 
}; 
"topic": { 
"primary": "Node.js", 
"secondary": [ 
"REST", 
"Architecture", 
"JavaScript" 


] 
}, 
"audience": { 
"takeaway": "Audience members will learn how to ...", 
"jobTitles": [ 
"Architects", 
"Developers" 


l 


"level": "Intermediate" 
Jo 
"installation": [ 
"Git", 
"Laptop", 
"Node.js" 
] 
} 


以 上 示例 包括 了 以 下 对 象 。 
speaker 
演讲 者 的 联系 信息 。 
session 
有 关 演 讲 的 描述 ， 包 括 标题 和 时 长 。 
Conference 
显示 演讲 者 申请 的 会 议 。MyConference 公司 同时 运营 多 个 会 议 ， 因 此 该 对 象 中 所 包含 
的 信息 是 十 分 重要 的 。 








topic 

演讲 中 涉及 的 主要 话题 和 次 要 话题 。 
audience 

目标 听众 的 范围 〈 初 级 、 中 级 或 者 高 级 ) o 
installation 


听众 在 与 会 前 应 当 事 先 做 好 的 软件 安装 工作 (如果 需 要 的 话 )。 
10.7.2 ”架构 中 的 组 件 


以 下 是 MyConference 应 用 程序 所 需要 的 组 件 。 
演讲 提案 生成 程序 
使 用 publish-message.sh 脚本 向 new-proposals-recvd 主题 发 送 JSON 形式 的 演讲 提案 。 
在 实际 的 产品 开发 中 ， 这 一 程序 的 形式 应 该 会 是 一 个 优雅 的 AngularJS 应 用 程序 ， 拥 有 
不 错 的 用 户 体验 设计 并 通过 RESTful API 进行 通信 ;， 不过， 为 了 专注 于 介绍 JSON， 我 
们 依旧 使 用 publish-message.sh 这 个 极为 简单 的 命令 行 脚本 工具 。 
提案 审核 程序 ( 即 消费 者 ) 
该 程序 会 监听 new-proposals-recvd 主题 ， 通 过 或 拒绝 某 个 提案 ， 然 后 向 proposals- 
reviewed 主题 发 送 相应 的 消息 以 供 后 续 处 理 。 在 实际 的 企业 级 架构 中 ， 一般 会 在 最 前 
面 配置 RESTful API 接口 来 接收 提案 请 求 ， 然 后 再 将 相应 的 消息 发 布 到 new-proposals- 
recvd 主题 中 。 不 过 与 之 前 的 生产 者 程序 一 样 ， 此 处 我 们 也 简化 了 示例 ， 不 使 用 任何 
API 组 件 。 
演讲 者 提醒 程序 ( 即 消费 者 ) 
该 程序 会 监听 proposals-reviewed 主题 ， 然 后 根据 审核 人 员 的 决定 生成 相应 的 通过 邮件 
或 拒绝 邮件 ， 最 后 向 演讲 者 发 送 提醒 邮件 。 
电子 邮件 服务 器 (模拟 ) 
该 服务 器 作为 MyConference 公司 的 邮件 服务 器 来 发 送 提醒 邮件 。 
电子 邮件 客户 总 (模拟 ) 
该 客户 端 作为 演讲 者 的 邮件 客户 端 来 接收 提醒 邮件 。 
我 们 将 使 用 MailCatcher 来 模拟 电子 邮件 的 客户 端 和 服务 器 端 ， 从 而 简化 程序 的 基础 设施 
设置 。 


图 10-1 展示 了 整个 应 用 程序 中 的 数据 流 和 各 个 组 件 间 的 交互 情况 。 
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E MyConference 演 讲 者 提案 应 用 系统 


UREA REF. TOP 消息 代理 
(技术 : Shell 脚 本 ) (技术 :Apache Kafka) 












演讲 者 提醒 程序 提案 审核 程序 











E (技术 : Be .. (技术 : Nodejs) 上 
i, ars metre 
p E ES Nn 
Comm 2 SMTP oe 
STE TIBE H 电子 邮件 服务 器 | 
(技术 : MailCatcher, (技术 : MailCatcher, 
HTML, Ruby on Rails) Ruby on Rails) 














10-1: MyConference 演讲 提案 系统 的 架构 

该 图 表 中 的 数据 流 如 下 所 示 。 

(1) 在 MyConference 应 用 程序 中 ， 演 讲 者 使 用 演讲 提案 生成 程序 向 new-proposals-recvd 主 
题 发 送 提 案 消 息 。 

(2) 提案 审核 程序 在 new-proposals-recvd 主题 上 收 到 新 的 提案 消息 ， 做 出 决策 ， 然 后 将 相 
应 的 通过 /拒绝 消息 发 送 到 proposals-reviewed 主题 中 。 

(3) 演 讲 者 提醒 程序 在 proposals-reviewed 主题 上 收 到 通过 /拒绝 的 消息 ， 然 后 创建 提醒 邮 
件 并 发 送 。 

(4) 演讲 者 查看 提醒 邮件 中 的 消息 。 

接 下 来 我 们 将 查看 具体 的 代码 ， 并 运行 这 一 示例 。 


组 件 











10.7.3 配置 Kafka 环 境 
如 果 你 运行 过 前 面 命令 行 的 示例 ， 那 么 接 下 来 的 步骤 就 会 显得 似曾相识 〈 可 以 回顾 之 前 的 
内 容 来 唤起 相关 记忆 )。 我 们 总 共 需 要 运行 4 个 命令 行 工 具 来 配置 本 示例 的 环境 。 执 行 以 
下 操作 。 
(1) 创建 命令 行 环境 1, 

。 启动 ZooKeeper。 

。 启动 Kafka。 
(2) 创建 命令 行 环境 2。 
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。 创建 proposals-reviewed 主题 。 
。 创建 new-proposals-recvd 主题 。 


完成 Kafka 核心 组 件 的 配置 后 ， 我 们 来 搭建 一 个 电子 邮件 服务 器 ， 以 接收 通过 /拒绝 提醒 
邮件 方面 的 消息 。 


10.7.4 ”配置 模拟 的 电子 邮件 服务 器 及 客户 端 一 一 MailCatcher 


我 们 将 使 用 MailCatcher 来 完成 这 一 功能 。 对 于 电子 邮件 测试 来 说 ， 简 单 的 邮件 服务 器 是 
一 个 不 错 的 工具 ， 因 为 使 用 这 一 工具 无 须发 送 真 实 邮件 即 可 完成 测试 。MailCatcher 具备 本 
示例 所 需要 的 很 多 特性 。 


。 遵循 标准 一 一 MailCatcher 遵循 简单 邮件 传输 协议 (Simple Mail Transfer Protocol, SMTP). 

。 安装 过 程 简 单 。 

。 启动 /关闭 过 程 简单 。 

。 安全 特性 是 可 选 的 。 我 知道 这 么 说 有 点 惊世骇俗 ， 但 事实 上 我 们 想 避 免 对 邮件 服务 器 的 
JH P ID/ 密码 进行 配置 所 带 来 的 一 大 堆 琐事 。 对 于 我 们 正在 开发 的 这 种 示例 项 目 或 者 原 
型 项 目 而 言 ， 这 么 做 完全 没 问 题 。 当 然 ， 对 于 比较 大 的 原型 应 用 程序 或 者 真实 的 产品 开 
发 来 说 ， 确 实 应 该 在 邮件 服务 器 上 添加 安全 限制 。 因 为 MailCatcher 也 可 以 进行 用 户 安 
全 配置 ， 所 以 完全 可 以 应 用 于 更 大 型 的 示例 项 目 。 

。 优秀 的 Web 用 户 界面 ， 可 以 显示 发 往 服务 器 的 邮件 消息 。 


如 需 了 解 更 多 有 关 MailCatcher 的 信息 ， 可 参考 其 官方 网 站 。 


如 尚未 安装 Ruby on Rails， 可 参考 A.3 节 中 的 内 容 来 执行 相关 的 安装 操作 。 在 命令 行 中 使 
用 以 下 方式 来 安装 mailcatcher 包 (可 参考 A.3.3 节 ) : 


gem install mailcatcher 


启动 MailCatcher 服务 器 ， 你 应 该 可 以 在 屏幕 上 看 到 相应 的 结果 : 


json-at-work => mailcatcher 

Starting MailCatcher 

==> smtp://127.0.0.1:1025 

==> http://127.0.0.1:1080 

*** MailCatcher runs as a daemon by default. Go to the web interface to quit. 


MailCatcher 以 daemon 进程 的 形式 在 后 台 运 行 ， 这 使 得 用 户 可 以 在 当前 命令 行 窗口 中 执行 
其 他 操作 。 我 们 将 在 需要 审核 邮件 时 访问 MailCatcher 的 Web 用 户 界面 (参见 10.7.9 节 )。 


10.7.5 配置 Node.js 项 目 环境 


提案 审核 程序 和 演讲 者 提醒 程序 都 是 使 用 Node.js 编写 的 。 如 尚未 安装 Node.js， 可 参考 
A.2 “iF A.2.5 市 中 的 内 容 来 执行 相关 的 安装 操作 。 如 需 依照 本 布 的 描述 运行 代码 示例 中 
的 Node.js 项 目 ， 可 使 用 cd 命令 切换 到 chapter-10/myconference 目录 ， 并 执行 以 下 命令 来 
安装 项 目 依 赖 : 


npm install 


如 需 手动 创建 本 节 中 的 Nodejs 项 目 ， 可 参考 本 书 在 GitHub 上 的 相关 指导 步 又 。 
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10.7.6 ”演讲 提案 生成 程序 〈 用 于 发 送 演讲 提案 ) 

我 们 会 使 用 之 前 的 publish-message.sh 脚本 将 speakerProposal.json 文件 中 的 内 容 发 送 到 new- 

proposals-recvd 主题 中 。 在 命令 行 窗 口 切换 到 scripts 目录 下 ， 运 行 以 下 命令 : 
./publish-message.sh -f ../data/speakerProposal.json new-proposals-recvd 


提案 审核 程序 会 随机 通过 /拒绝 提案 (参见 10.7.7 节 )， 因 此 你 可 能 需要 运行 3~5 次 (或 者 
更 多 ) 脚本 后 才能 既得 到 通过 的 提醒 消息 ， 又 得 到 拒绝 的 消息 。 


10.7.7 ”提案 审核 程序 “消息 的 消费 者 和 生产 者 ) 

提案 审核 程序 会 执行 以 下 操作 。 

。 监听 new-proposals-recvd 主题 来 接收 演讲 者 的 提案 。 

。 检查 提案 并 决定 通过 还 是 拒绝 。 

。 将 有 关 提 案 的 决定 发 送 到 proposals-reviewed 主题 中 ， 以 供 后 续 处 理 。 
myconference/proposalReviewer.js 文件 中 包含 了 所 有 的 提案 审核 应 用 程序 。 例 10-11 展示 了 
其 中 一 部 分 代码 ， 主 要 是 关于 接收 new-proposals-recvd 主题 上 的 演讲 提案 以 及 相关 配置 
方面 的 情况 。 


例 10-11 myconference/proposalReviewer.js 
var kafka = require('kafka-node'); 









































const NEW PROPOSALS RECEIVED TOPIC = 'new-proposals-recvd'; 


var consumer = new kafka.ConsumerGroup({ 
fromOffset: 'latest', 
autoCommit: true 

), NEW PROPOSALS RECEIVED TOPIC); 














// 使 用 接收 到 的 JSON 消 息 。 
// 使 用 JSON.parse() 和 ]JSON.stringify() 来 处 理 JSON。 
consumer.on('message', function(message) { 
// console.log('received kafka message', message); 
processProposal(message); 


p; 











consumer.on('error', function(err) { 
console. Log(err); 


}); 


process.on('SIGINT', function() { 
console. log( 
'SIGINT received - Proposal Reviewer closing. 
'Committing current offset on Topic: ' + 
NEW PROPOSALS RECEIVED TOPIC + ' ...' 


T 








)3 


consumer.close(true, function() { 


console. log( 


"Finished committing current offset. Exiting with graceful shutdown ... 


)$ 


process.exit(); 
3 
H; 


在 以 上 示例 中 ， 需 要 注意 以 下 几 点 。 





。 kafka-node 这 一 npm 模块 用 于 生产 /消费 Kafka 中 的 消息 。 可 以 在 kafka-node 的 npm 
主页 及 GitHub 主页 上 找到 更 多 信息 。 

。 监听 new-proposals-recvd 主题 并 使 用 其 中 的 消息 。 

实例 化 一 个 ConsumerGroup 对 象 ， 并 通过 该 对 象 使 用 new-proposals-recvd 主题 中 


例 10-12 展示 了 如 何 校 验 演讲 提案 六 


的 Kafka 消息 。fromoffset: 





"latest! 参数 表示 我 们 需要 接收 该 主题 的 最 新 消息 ， 





autoCommit: true 参数 则 表示 使 用 每 条 消息 后 就 自动 提交 (这样 该 消息 会 标记 为 “已 


处 理 ”)。 








consumer.on('message' ...) 监听 消息 并 调用 processProposal() 函数 来 处 理 新 接收 
到 的 演讲 提案 。 后 面 我 们 会 再 详细 介绍 processProposal() 函数 。 
consumer.on('error' ...) 在 处 理 消息 过 到 报错 时 会 将 错误 消息 打印 出 来 。 
process.on('SIGINT' ...) 监听 SIGINT 信号 (关闭 进程 )， 提 交 当 前 的 偏 移 量 并 优雅 


地 退出 程序 。 











+ consumer.close(...) 提交 当前 的 偏 移 量 。 该 操作 确保 当前 的 消息 被 标记 为 已 读 ， 
而 程序 重启 后 ， 监 听 相 关 主 题 的 消费 者 程序 就 可 以 收 到 新 的 消息 了 。 








F 做 出 决定 。 





f] 10-12 myconference/proposalReviewer.js 


var fs - require('fs'); 
var Ajv = require('ajv'); 


const SPEAKER PROPOSAL SCHEMA FILE NAME - 
' . [schemas/speakerProposalSchema.json'; 


function processProposal(proposal) { 
var proposalAccepted - decideOnProposal(); 
var proposalMessage - proposal.value; 
var proposalMessageObj = JSON.parse(proposalMessage); 


console. log('\n\n'); 


console. log('proposalMessage = 


1 


+ proposalMessage); 


1 


console. log('proposalMessageObj = ' + proposalMessageO0bj); 
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console.log('Decision - proposal has been [' + 
(proposalAccepted ? 'Accepted' : 'Rejected') + ']'); 


if (isSpeakerProposalValid(proposalMessageObj) && proposalAccepted) { 
acceptProposal(proposalMessage0bj); 
} else { 
rejectProposal(proposalMessage0bj); 
} 
} 


function isSpeakerProposalValid(proposalMessage) { 
var ajv = Ajv({ 
allErrors: true 


J; 


var speakerProposalSchemaContent = fs.readFileSync( 
SPEAKER PROPOSAL SCHEMA FILE NAME); 


var valid - ajv.validate(speakerProposalSchemaContent, proposalMessage); 


if (valid) ( 
console. log('\n\nJSON Validation: Speaker proposal is valid'); 

} else { 
console. log('\n\nJSON Validation: Error - Speaker proposal is invalid'); 
console. log(ajv.errors + '\n'); 


} 


return valid; 


j 


function decideOnProposal() { 
return Math.random() »- 0.5; 


j 


function acceptProposal(proposalMessage) { 
var acceptedProposal - ( 
decision: { 
accepted: true, 


timeSlot: { 
date: "2017-11-06", 
time: "10:00" 
} 
}, 
proposal: proposalMessage 


5 


var acceptedProposalMessage - JSON.stringify(acceptedProposal); 
console.log('Accepted Proposal = ' + acceptedProposalMessage); 
publishMessage(acceptedProposalMessage); 


j 


function rejectProposal(proposalMessage) { 
var rejectedProposal - ( 
decision: { 





提 


accepted: false 


} 


proposal: proposalMessage 


5 


var rejectedProposalMessage - JSON.stringify(rejectedProposal); 
console.log('Rejected Proposal = ' + rejectedProposalMessage); 
publishMessage(rejectedProposalMessage); 


案 审 核 程序 收 到 演讲 提案 的 消息 后 ，processProposal() 函数 会 执行 以 下 操作 。 








decideOnProposal() 会 随机 决定 通过 或 者 拒绝 提案 ， 从 而 简化 逻辑 。 在 真实 的 系统 中 ， 

应 用 程序 会 将 提案 发 送 到 某 个 人 的 工作 邮箱 ， 由 人 工 进行 审核 并 做 出 决定 。 

JSON.parse() 会 解析 提案 消息 ， 确 保 其 语法 正确 (遵循 基本 的 ISON 格式 规则 )。 

isSpeakerProposalValid() 函数 使 用 ajv 模块 ,根据 JSON Schema(schemas/speakerProposal 

Schema.json) 校 验 消息 。 

— 可 回顾 第 5 章 中 有 关 JSON Schema WAZ. 

- 根据 JSON Schema 进行 校 验 可 以 确保 消息 在 语义 上 的 正确 性 (消息 数据 具备 处 理 提 
案 需要 的 所 有 字段 )。 

一 可 以 在 ajv 的 npm 主页 和 GitHub 主页 上 找到 更 多 相关 信息 。 

如 果 提 案 通 过 ，acceptProposal() 会 执行 以 下 操作 。 

- 创建 一 个 表示 提案 通过 的 对 象 ， 对 象 中 包含 提案 通过 的 相关 字段 ， 以 及 演讲 者 将 在 
会 议 上 进行 演说 的 具体 时 间 信 息 。 

— 使 用 JSON.stringify() 将 该 对 象 转换 为 JSON。 

一 调用 publishMessage() 将 提案 通过 的 消息 发 布 到 proposals-reviewed 主题 中 。 

如 果 提 案 被 拒绝 (或 格式 不 正确 )，rejectProposal() 会 执行 以 下 操作 。 

- 创建 一 个 表示 拒绝 提案 的 对 象 ， 对 象 中 包含 拒绝 提案 的 相关 字段 。 

— 使 用 ISON.stringify() 将 该 对 象 转换 为 JSON, 

一 调用 publishMessage() 将 拒绝 提案 的 消息 发 布 到 proposals-reviewed 主题 中 。 






































例 10-13 展示 了 如 何 将 通过 /拒绝 的 消息 发 布 到 proposals-reviewed 主题 中 。 


例 10-13 myconference/proposalReviewer.js 


const PROPOSALS REVIEWED TOPIC = 'proposals-reviewed'; 


var producerClient - new kafka.Client(), 
producer - new kafka.HighLevelProducer(producerClient); 


function publishMessage(message) { 
var payloads = [{ 
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topic: PROPOSALS REVIEWED TOPIC, 
messages: message 


11; 


producer.send(payloads, function(err, data) { 
console.log(data); 
DH 
} 


producer.on('error', function(err) { 
console.log(err); 


D; 
这 段 代码 使 用 了 以 下 方式 将 消息 发 布 到 proposals -reviewed 主题 中 。 


© 实例 化 并 使 用 HighLevelProducer 对 象 将 消息 发 布 到 proposals-reviewed 主题 中 。 事 实 
上 ，HighLevelProducer 对 象 的 实例 化 发 生 在 程序 文件 的 开头 ， 但 为 方便 起 见 ， 例 10-13 
对 其 进行 了 展示 。 

e publishMessage() 调用 producer.send() 来 发 送 消息 。producer.on('message' ...) MIK 
听 消 息 ， 并 在 收 到 新 的 演讲 提案 后 调用 processProposal() 来 进行 处 理 (后 文 将 详细 介 
绍 这 一 过 程 )。 

在 前 面 的 内 容 中 ， 我 们 只 介绍 了 消息 的 生产 者 和 消费 者 使 用 的 kafka-node 对 象 。 如 需 了 解 

更 多 详情 ， 可 访问 kafka-node 模块 的 文档 页 面 来 学 习 以 下 概念 的 相关 内 容 : 


。 HighLevelProducer 

































































e ConsumerGroup 
。 Client 


探讨 了 提案 审核 程序 后 ， 现 在 我 们 创建 一 个 新 的 命令 行 窗口 ， 并 在 myconference 路 径 下 运 
行 以 下 命令 来 启动 该 提案 审核 程序 : 

node proposalReviewer.js 
当 演 讲 提 案 消 息 发 送 到 new-proposals-recvd 主题 时 ， 你 应 该 可 以 观察 到 提案 审核 程序 对 
该 消息 的 日 志 记 录 ， 以 及 在 proposals-reviewed 主题 上 所 进行 的 相关 决策 信息 : 


json-at-work => node proposalReviewer. js 

















proposalMessage = { "speaker": { "firstName": "Larson", "LastName": "Richard", "email": “Larson.richard@ecratic.com", "bi 
: "Larson Richard is the CTO of ... and he founded a JavaScript meetup in ..." }, "session": { "title": "Enterprise Nod 
abstract": "Many developers just see Node as a way to build web APIs or applications b ": "How-To", "length 
hours" }, "conference": { "name": "Ultimate JavaScript Conference by MyConference", "beg ": "2017-11-06", "end 
: "2017-11-10" }, "topic": ( "primary": "Node.js", "secondary": [ "REST", "Architecture", "JavaScript" ] }, "audienc 
takeaway": "Audience members will learn how to ...", "jobTitles": [ "Architects", "Developers" ], "level": "Interm 
ediate" }, "installation": [ "Git", "Laptop", "Node.js" ] } 
proposalMessage0bj - [object Object] 
Decision - proposal has been [Accepted] 


JSON Validation: Speaker proposal is valid 
Accepted Proposal - ("decision imeSlot": "date": "2017-11 i "10:00"}}, "proposal" : "speaker" :( 
"firstName" : "Larson" , “LastName 1Larso rdeecratic.com io": Richard is the CTO of ... an 


d he founded a JavaScript meetup in ..." i ise Node","abstract":"Many developers just see Node 


as a way to build web APIs or applications . "type" : "I ' "length" :"3 hours"), "conference": ("name":"Ultimate JavaSc 
ript Conference by MyConference" , "beginDate" : "2017-11-06" , "endDate" : "2017-11-10" , "topic" : ("primary" : "Node. js" , "secondary 
"S ["REST", "Architecture" , "JavaScript"]}, "audience": ("takeaway" : "Audience members will learn how to ...","jobTitles":["Arc 
hitects", "Developers"], "level":"Intermediate"], "installation": ["Git", "Laptop", "Node. js"]}} 

{ 'proposals-reviewed': { '0': 12 } } 








10.7.8 演讲 者 提醒 程序 〈 消 息 的 消费 者 ) 

对 提案 做 出 通过 或 者 拒绝 的 决定 后 ， 演 讲 者 提醒 程序 会 执行 以 下 操作 。 
。 监听 proposals-reviewed 主题 中 通过 /拒绝 提案 的 消息 。 

。 格式 化 通过 或 拒绝 提案 的 电子 邮件 。 
。 发 送 通过 或 拒绝 提案 的 电子 邮件 。 
myconference/speakerNotifier.js 文件 中 包含 了 完整 的 演讲 者 提醒 应 用 程 
接收 proposals-reviewed 主题 中 通过 /拒绝 提案 消息 的 部 分 代码 。 


例 10-14 myconference/speakerNotifier.js 
var kafka = require('kafka-node'); 


ay 





m 





const PROPOSALS REVIEWED TOPIC - 'proposals-reviewed'; 


var consumer = new kafka.ConsumerGroup({ 
fromOffset: 'latest', 
autoCommit: true 

), PROPOSALS REVIEWED TOPIC); 


consumer.on('message', function(message) { 
// console.log('received message', message); 
notifySpeaker(message.value); 


p; 


consumer.on('error', function(err) { 
console.log(err); 


p); 


process.on('SIGINT', function() { 
console. log( 
'SIGINT received - Proposal Reviewer closing. 
'Committing current offset on Topic: ' + 
PROPOSALS REVIEWED TOPIC + ' ...' 
); 


+ 


consumer.close(true, function() { 
console. log( 


"Finished committing current offset. Exiting with graceful shutdown ... 


3s 


process.exit(); 
IDE 
DE 


FF. ffl 10-14 展示 了 
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演讲 者 提醒 程序 使 用 以 下 方式 监听 并 使 用 proposals- reviewed 主题 中 的 消息 。 





。 实例 化 并 利用 ConsumerGroup 对 象 来 使 用 proposals-reviewed 主题 中 的 Kafka 消息 。 提 


醒 程 序 的 初始 配置 工作 与 提案 审核 程序 的 代码 类 似 。 




















e consumer.on('message' ...) 监听 消息 , 并 在 收 到 新 的 提案 审核 结果 后 调用 notifySpeaker() 











来 进行 处 理 (后 文 将 详细 介绍 这 一 过 程 )。 


e consumer.on('error' ...) 和 process.on('SIGINT' ...) 国 数 的 作用 与 提案 审核 程序 中 


的 相同 。 




















例 10-15 展示 了 如 何 处 理 提案 的 通过 /拒绝 消息 ， 并 使 用 Handlebars 将 结果 格式 化 为 相应 





的 电子 邮件 〈 详 见 第 7 章 )。 
例 10-15  myconference/speakerNotifier.js 


var handlebars = require('handlebars'); 
var fs = require('fs'); 


const EMAIL FROM = 'proposals@myconference.com'; 
const ACCEPTED PROPOSAL HB TEMPLATE FILE NAME - 
' . /templates/acceptedProposal.hbs'; 


const REJECTED PROPOSAL HB TEMPLATE FILE NAME - 
' .[templates/rejectedProposal.hbs'; 


const UTF 8 - 'utf8'; 


function notifySpeaker(notification) { 
var notificationMessage - createNotificationMessage(notification); 


sendEmail(notificationMessage); 


j 


function createNotificationMessage(notification) { 
var notificationAsObj - JSON.parse(notification); 
var proposal - notificationAsObj.proposal; 
console.log('Notification Message = ' + notification); 
var mailOptions = { 
from: EMAIL FROM, // 发 送 者 地 址 
to: proposal.speaker.email, // 接受 者 列 于 





- n 


subject: proposal.conference.name + ' - ' + proposal.session.title, // 4 


html: createEmailBody(notificationAsObj) 
E 


return mailOptions; 


j 


function createEmailBody(notification) { 


FH 
& 








提醒 程序 收 到 通过 /拒绝 提案 的 消息 后 ，notifySpeaker() 函数 会 执行 以 下 操作 。 
调用 createNotificationMessage() 来 创建 发 送 给 演讲 者 的 提醒 邮件 。 

— 使 用 JSON.parse() 将 通过 /拒绝 提案 的 消息 解析 为 对 象 。 

— 调用 createEmailBody()。 

4 根据 上 述 解析 后 的 对 象 ,使 用 handlebars 模块 来 生成 HTML 格式 的 电子 邮 们 


// 阅读 HandLebars 模 板 文件 。 


var hbTemplateContent = fs.readFileSync(((notification.decision.accepted) ? 


ACCEPTED PROPOSAL HB TEMPLATE FILE NAME : 
REJECTED PROPOSAL HB TEMPLATE FILE NAME), UTF. 8); 


// 将 模板 编译 为 一 个 方程 。 
var template = handlebars.compile(hbTemplateContent); 
var body = template(notification); // 演 染 模板 。 


console.log('Email body = ' + body); 
return body; 








€ 可 参考 第 7 章 来 回顾 有 关 Handlebars MAA. 
e 如 需 了 解 更 多 信息 ， 可 参考 handlebars 的 npm 主页 与 GitHub 主页 。 





调用 sendEmail() 将 提醒 邮件 发 送 给 演讲 者 (参见 以 下 示例 )。 





例 10-16 展示 了 发 送 通过 /拒绝 邮件 的 过 程 。 
例 10-16 myconference/speakerNotifier.js 





var nodeMailer = require('nodemailer'); 


const MAILCATCHER_SMTP_HOST 
const MAILCATCHER_SMTP_PORT 


'localhost'; 
1025; 


var transporter - nodeMailer.createTransport(mailCatcherSmtpConfig); 


function sendEmail(mailOptions) { 
// 通过 已 定义 的 运输 对 象 发 送 邮 件 
transporter.sendMail(mailOptions, function(error, info) { 
if (error) { 
console.log(error); 
) else { 
console.log('Email Message sent: ' + info.response); 
} 
IDE 
} 


消息 o 
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演讲 者 提醒 程序 使 用 以 下 方式 将 邮件 消息 发 送 到 MailCatcher 服务 





。 实例 化 并 使 用 nodemailer 传输 对 象 来 发 送 电子 邮件 。MAILCATCHER_SMTP_... 常量 用 于 保 
存 本 机 所 启动 的 MailCatcher 服务 器 的 地 址 与 端口 。nodematter 传输 对 象 的 实例 化 实际 








发 生 在 文件 开头 ， 出 于 方便 的 目的 ， 上 述 示 例 对 其 进行 了 展示 。 
e sendEmail() 国 数 调用 transporter.sendMail() d 











e nodemailer 是 一 个 使 用 SMTP 来 发 送 邮件 消息 的 通用 npm 模块 。 如 需 了 解 更 多 信息 ， 

















可 参考 其 npm 主页 及 社区 主页 。 





现在 我 们 打开 一 个 新 的 命令 行 窗口 ， 在 myconference 路 径 下 运行 以 下 命令 来 启动 演讲 者 提 








醒 程 序 ， 


node speakerNotifier.js 








24 proposals-reviewed 主题 收 到 通过 /拒绝 提案 的 消息 时 ， 你 应 该 可 以 观察 到 演讲 者 提醒 





程序 对 该 消息 的 日 志 记 录 ， 以 及 其 发 送 的 提醒 邮件 : 


json-at-work => node speakerNotifier.js 
Notification Message - decision" V "accepted" :true, "tineSlot" : {"date”:"2017-11-06" ,"time":"10:00"}}, "proposal": {"speaker 
":{"firstName": "Larson", "LastName": "Richard", “email":"Larson.richard@ecratic.com","bio":"Larson Richard is the CTO of . 
and he founded a JavaScript meetup in ... "y i i "Enterprise Node", "abstract": "Many developers just see No 
ae "UL 


de as a way to build web APIs or applications ngth":"3 hours" LM 
aScript Conference by MyConference" , "beginDat: 201 is 
ary": ["REST", "Architecture", "JavaScript" "]}, "aud Hi jay": Hence members will learn how to ...", MAD 
Architects", "Developers"], "level":"Intermediate"] , "installation":[' " , "Laptop", "Node. js" 113 
Email body = «!DOCTYPE html» 
«html» 
<body> 
<p> 
Larson, 
</p> 


<p> 

We are pleased to inform you that your talk on «Enterprise Node</u> 

has been accepted for the <b>Ultimate JavaScript Conference by MyConference</b>. 
</p> 

<p> 

Your session scheduled for 2017-11-06 at 10:00. 

</p> 


<p> 
Sincerely, <br/> 
The Ultimate JavaScript Conference by MyConference Event Team. 
</p> 
</body> 
</html> 
Email Message sent: 250 Message accepted 


10.7.9 用 MailCatcher 实 现 审核 结果 的 电子 邮件 提醒 功能 
最 后 ， 我 们 查看 一 下 由 提醒 程序 所 生成 并 发 送 到 演讲 者 的 提醒 消息 。 











在 本 机 访问 http://localhost:1080 即 可 看 到 MailCatcher 的 用 户 界 面 。 
面 ， 其 中 列举 了 MyConference 应 用 程序 通过 Handlebars 生成 的 电子 邮件 消息 。 
































到 10-2 展示 了 概要 页 








© MailCatcher s ssages Clar | Qui 




















From To Subject Received. 
«proposals Q myconference.com» <larson.richard@ecratic.com> Ultimate JavaScript Conference by MyConference - Enterprise Node ‘Saturday, 21 Jan 2017 4:18:02 PM 
«proposals Q myconference.com» <larson.richard@ecratic.com> Ultimate JavaScript Conference by MyConference - Enterprise Node ‘Saturday, 21 Jan 2017 4:17:49 PM 
«proposals Q myconference.com» <larson.richard@ecratic.com> Ultimate JavaScript Conference by MyConference - Enterprise Node Saturday, 21 Jan 2017 3:28:31 PM 
<proposals@myconference.com> <larson.richard@ecratic.com> Ultimate JavaScript Conference by MyConference - Enterprise Node ‘Saturday, 21 Jan 2017 12:50:06 PM 
Received 
From 
To 
Subject 
HTML  PlainText Source. Download 
; EN Bran 
图 10-2; MailCatcher 中 的 演讲 者 提醒 消息 
点 其 中 iE 件 有 些 牛 显示 提案 审核 通 0-3 所 示 
点 击 其 些 邮 4 , 些 邮 人 4 MEAN TE FH PA a, 10- 人 小。 
© MailCatcher arch messa Char | Qui 
From To Subject. Received. 
proposals? myconference.com»- -larson.richard@ecratic.com> Ultimate JavaScript Conference by MyConference - Enterprise Node ‘Saturday, 21 Jan 2017 4:18:02 PM 
«proposals à) myconference.com» <larson.richard G'ecratic.com». Ultimate JavaScript Conference by MyConference - Enterprise Node Saturday, 21 Jan 2017 4:17:49 PM 
«proposals à myconference.com» <larson.richard@ecratic.com> Ultimate JavaScript Conference by MyConference - Enterprise Node Saturday, 21 Jan 2017 3:28:31 PM 
«proposals à myconference.com» <larson.richard@ecratic.com> Ultimate JavaScript Conference by MyConference - Enterprise Node Saturday, 21 Jan 2017 12:50:06 PMo, agit Editor 





Received Saturday, 21 Jan 2017 4:18:02 PM 
From <proposals@myconference.com> 
To <larson.richard@ecratic.com> 
Subject Ultimate JavaScript Conference by MyConference - Enterprise Node 


"ma. |e Download 


Larson, 
We are pleased to inform you that your talk on Enterprise Node has been accepted for the Ultimate JavaScript Conference by MyConference. 
Your session scheduled for 2017-11-06 at 10:00. 


Sincerely, 
The Ultimate JavaScript Conference by MyConference Event Team. 








& 10-3; MailCatcher 中 的 演讲 提案 通过 消息 


图 10-4 则 显示 了 一 封 拒绝 提案 的 邮件 。 
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Received Saturday, 21 Jan 2017 4:17:49 PM 
From «proposalsGmyconference.com» 
To <larson.richard@ecratic.com> 
Subject Ultimate JavaScript Conference by MyConference - Enterprise Node 


HTML | Source 
Larson, 

We appreciate your interest, but regret to inform you that your talk on Enterprise Node was not accepted for the Ultimate JavaScript Conference by MyConference. 
We look forward to seeing you at future events, and hope that you submit more conference talks. 


Sincerely, 
The Ultimate JavaScript Conference by MyConference Event Team. 











10-4; MailCatcher 中 拒绝 演讲 提案 的 消息 














MailCatcher 的 Web 用 户 界 面 的 工作 机 制 如 下 。 


。 可 以 点 击 Download 按钮 来 下 载 当 前 的 电子 邮 伯 
式 的 文件 (后 级 名 为 eml), IZA: 
— 遵循 了 MIME 822 标准 ; 
一 与 以 下 邮件 客户 端 兼容 : MS Outlook, Outlook Express, Apple Mail, Mozilla Thunderbird 等 ; 
— 保留 了 原始 的 HTML 格式 及 邮件 头 。 

。 可 以 点 击 页 面 右上 角 的 Quit 按钮 来 关闭 MailCatcher 后 台 进 程 。 


10.8 ”本章 回顾 
本 章 介绍 了 以 下 内 容 。 


。 在 命令 行 中 使 用 Kafka 来 生成 /使 用 JSON 消息 。 
。 设计 并 实现 一 个 小 型 的 端 到 端 MyConference 示例 应 用 程序 ,该 应 用 程序 采用 Kafka 主题 、 
ode.js 和 模拟 的 电子 邮件 服务 器 来 处 理 基 于 JSON 的 演讲 者 应 用 程序 。 


tr 


。 该 操作 会 将 邮件 消息 保存 为 EML 格 























Z 





附录 人 


dH 





该 附录 将 介绍 与 本 书 代码 示例 有 关 的 软件 安装 与 配置 。 


A.1 在 浏览 器 中 安装 JSON 工 具 


这 部 分 内 容 将 介绍 如 何在 浏览 器 中 安装 ISON 工具 。 





A.1.1 在 Chrome 和 Firefox 中 安装 JSONView 

JSONView 可 以 在 Chrome 和 Firefox 中 优化 显示 JSON。 你 可 以 参考 JSONView 网 站 上 的 
安装 步骤 在 自己 的 训 览 器 上 进行 相应 的 安装 。 

A.1.2 JSONLint 

可 以 使 用 JSONLint 来 在 线 校 验 JSON 文档 。JSONLint 无 须 安装 。 


A.1.3 JSON Editor Online 


可 以 使 用 JSON Editor Online 对 JSON 文档 进行 建 模 。 作 为 Web 应 用 程序 ，JSON Editor 
Online 无 须 安装 即 可 使 用 。 


A.1.4 安装 Postman 


可 以 使 用 Postman 对 RESTful API 进行 完整 的 测试 。Postman 可 以 发 送 HTTP GET, POST, 
PUT 和 DELETE 请 求 ， 也 可 以 设置 HTTP 头 部 。 你 可 以 Chrome 插件 的 形式 来 安装 Postman, 
也 可 将 其 安装 为 macOS、Linux 或 Windows 上 的 独立 GUI 应 用 程序 。 关 于 安装 步骤 ， 可 
参考 其 官方 网 站 。 
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A.2 安装 Node.js 
本 书 使 用 的 Node.js 版 本 为 v6.10.2， 即 撰写 本 书 时 的 最 新 稳定 版 。 








A.2.1 用 NVM 在 macOS 和 Linux 上 安装 Node.js 


虽然 可 以 在 Nodejs 的 官方 网 站 上 找到 安装 包 并 进行 安装 ， 但 使 用 这 种 安装 方式 后 不 太 容 
易 更 换 Node.js 的 版 本 。 因 此 ， 我 们 使 用 NVM (Node Version Manager, Node 版 本 管理 器 
来 完成 Node js 的 安装 工作 。NVM 使 得 Node js 的 安装 、 印 载 和 版 本 升级 变 得 更 加 简单 。 
1. 安装 配置 NVM 
首先 ， 使 用 以 下 两 种 方式 之 一 来 安装 NVM: 
。 安装 脚本 ，; 
。 手动 安装 。 
然后 ， 确 保 NVM 可 以 正常 运行 。 在 命令 行 中 对 其 执行 source 操作 : 
source ~/.nvm/nvm.sh 

操作 完成 后 ，NVM 即 可 在 接 下 来 的 安装 过 程 中 正常 工作 。 
如 果 运 行 的 命令 行 环境 是 bash， 则 可 通过 以 下 操作 使 得 命令 行 对 NVM 进行 自动 配置 。 
。 在 $HOME/.bashrc 文件 中 添加 以 下 代码 。 
source ~/.nvm/nvm.sh export NVM_HOME=~/.nvm/v6.10.2 
e JE $HOME/.bashrc_profile 文件 中 添加 以 下 代码 。 

[[ -s SHOME/.nvm/nvm.sh ]] && . SHOME/.nvm/nvm.sh # This loads NVM 
值得 注意 的 是 ，Bourne Shell 和 Korn Shell 中 的 有 些 步骤 非常 类 似 。 
2. 用 NVM 安 装 Node.js 
安装 好 NVM 后 ， 即 可 用 其 来 安装 Nodejs。 


(1) 运行 nvm ls-remote 来 查看 可 安装 的 远 端 (不 在 本 机 上 ) Node.js 版 本 。 
(2) 使 用 以 下 命令 来 安装 v6.16.2 版 本 的 Node.js。 


nvm install v6.10.2 
。 所 有 版 本 的 Node.js 都 会 安装 到 SHOME/ .nvm 中 。 
(3) 在 所 有 的 新 命令 行 环境 中 设置 默认 的 Node.js 版 本 。 
nvm alias default v6.10.2 


。 如 果 忽 略 这 步 操作 ， 则 退出 当前 命令 行 环境 后 node 和 npm 命令 将 不 再 生效 。 
。 操作 完成 后 ， 退 出 当前 命令 行 环 境 。 
在 新 的 命令 行 环境 中 ， 将 npm 升级 至 最 新 版 本 。 


npm update -g npm 





























— 
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然后 ， 执 行 以 下 的 检查 确认 工作 : 


e nvm Ls， 可 以 观察 到 ... -> v6.10.2 system default -> v6.10.2; 
e node -v， 返 回 结果 为 v6.10.2; 
。 npm -v， 返 回 结果 类 似 4.6.1, 


如 需 查看 NVM 的 所 有 功能 ， 可 使 用 nvm --help。 
如 果 使 用 Node.js 的 “ 读 取 一 求 值 一 输出 一 循环 ”这 个 交互 式 编程 环境 ， 则 可 以 观察 到 以 
下 结果 : 


json-at-work => node 
-> .exit 


3. 避免 使 用 sudo 

npm 命令 可 能 会 要 求 使 用 sudo 权限 ,但 这 会 造成 繁琐 与 不 便 。 同 时 ， 给 予 npm 命令 sudo 
权限 也 会 带 来 安全 隐患 ， 因 为 npm 会 用 root 权限 来 运行 可 执行 脚本 。 为 了 避免 这 一 点 ， 可 
执行 以 下 操作 : 


sudo chown -R SUSER ~/.nvm 


如 果 你 的 Node.js 是 用 NVM 安装 的 (这 意味 着 所 有 的 Node.js 安装 都 会 在 ~/.nvm 路 径 下 进 
行 )， 则 上 述 操作 可 以 成 功 避 免 对 sudo 的 使 用 。 这 一 技巧 源 于 Isaac Z. Schlueter 在 How to 
Node 网 站 中 撰写 的 一 篇 文章 。 
4. 优化 REPL 一 一 mynode 
从 使 用 者 的 角度 来 看 ，REPL 的 默认 行为 有 值得 改进 之 处 。 默 认 情 况 下 ， 敲 击 回 车 键 后 ， 
对 于 大 多 数 JavaScript 语句 ，REPL 都 会 显示 undefined。 这 一 行为 的 原因 在 于 : JavaScript 
中 的 函数 总 是 会 返回 一 些 值 ， 而 在 没有 显 式 声 明 返 回 值 的 情况 下 会 默认 返回 undefined, 
这 一 行为 低 效 而 又 不 便 。 以 下 是 其 中 一 个 示例 : 

json-at-work => node 

-> Hit Enter 

-» undefined 

-> var y = 5 


-> undefined 
-> .exit 


可 以 在 .bashrc 文件 (或 者 Bourne/Korn Shell 中 的 其 他 启动 配置 文件 ) 中 添加 以 下 代码 来 
关闭 REPL 中 的 undefined 显示 。 









































source ~/.nvm/nvm.sh 


alias mynode="node -e \"require('repl').start({ignoreUndefined: true})\"" 
添加 代码 后 ， 退 出 当前 命令 行 环境 ， 然 后 再 重新 打开 一 个 命令 行 窗 口 。 像 这 样 定 义 一 个 新 
的 别名 ( 即 mynode) 比重 新 定义 node 要 更 安全 。 在 这 种 方式 下 ，node 依旧 可 以 在 命令 行 中 
正常 工作 ， 并 成 功 运行 JavaScript 文件 。 与 此 同时 ， 可 以 使 用 mynode 作为 新 的 REPL 命令 : 
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json-at-work => mynode 
-> var xX = 5 
-> .exit 
至 此 ，Node.js 中 的 REPL 就 可 以 如 预期 般 工作 了 ， 因 为 屏幕 上 不 会 再 显示 繁琐 不 便 的 


undefined, 








A.2.2 在 Windows 上 安装 Node.js 


多 亏 了 Corey Butler 的 nvn-windows 应 用 程序 NVM 也 可 以 在 Windows 上 正常 工作 。 
nvm-windows 是 nvm 在 Windows 环境 中 的 移植 版 本 。 我 可 以 在 Windows 7 环境 中 成 功 使 用 
nvm-windows, 


mo 


用 nvm-windows 在 Windows 上 安装 Node.js 
以 下 是 具体 的 安装 步骤 。 


(访问 nvm-windows 的 下 载 页 面 。 
(2) 将 最 新 的 nvm-setup.zip 文件 下 载 到 本 机 的 Downloads XHK. 
(3) 使 用 自己 喜欢 的 工具 来 解压 nvm-setup.zip 文件 。 
(4) 运行 nvm-setup.exe 来 启动 安装 向 导 。 使 用 向 导 中 的 默认 设置 并 接受 软件 的 MIT 许可 证 。 
a. 下 载 地 址 为 C:\Users{username}\AppData\Roaming\nvm, 
b. 安装 完成 后 ， 点 击 Finish 按钮 。 
c. 安装 过 程 中 会 在 Windows 机 器 上 配置 运行 Node.js 所 必需 的 环境 变量 。 
(5) 确保 PATH 环境 变量 中 包含 NVM. 
a. 打开 控制 面板 一 系统 一 高 级 系统 设置 。 
b. 在 高 级 系统 设置 窗口 中 点 击 “ 环 境 变量 ”。 
c. 之 前 的 安装 过 程 应 该 已 经 将 NVM_HOME 添加 到 环境 变量 中 ， 其 值 为 C:\Users {username }\ 
AppData\Roaming\nvm, 
d. NVM_SYMLINK 环境 变量 应 当 指向 C:\Program Files\nodejs, 
e. PATH 环境 变量 中 应 当 包 括 NVM_HOME 和 NVM_SYMLINK, 
(6) 用 nvm-windows 安装 Node.js。 
a. 运行 nvm list available 来 查看 可 安装 的 版 本 。 
b. 运行 nvm install v6.10.2, 
c. 设置 Node.js 的 版 本 : nvm use v6.10.2, 
d. 测试 刚 安装 的 Node: node -v。 
























































A.2.3 #)#KNode.js 

如 果 当 前 机 器 上 安装 过 Node.js， 但 已 经 无 法 正常 工作 ， 那 么 你 可 能 需要 将 其 完全 务 载 。 需 
要 御 载 的 可 执行 文件 包括 node fI npm, 

1. fgmacOS. Epi Node. js 


务 载 工作 比较 复杂 ， 本 书 中 的 伸 载 操作 源 自 Clay 在 Hungred Dot Com 网 站 上 所 发 表 的 文章 。 
如 果 Node.js 是 使 用 Homebrew 来 安装 的 ， 则 在 命令 行 中 运行 brew uninstall node 即 可 。 




















266 | MIA 


如 果 Node.js 不 是 使 用 Homebrew 来 安装 的 ， 则 可 执行 以 下 操作 。 


。 用 cd 命令 切换 到 /usr/local/lib 路 径 , 删 除 所 有 的 node 可 执行 文件 和 node_modules 文件 夹 。 

。 用 cd 命令 切换 到 /usr/local/include 路 径 ， 删 除 所 有 的 node 可 执行 文件 和 node, modules 
文件 夹 。 

。 用 cd 命令 切换 到 /usr/local/bin 路 径 ， 删 除 所 有 的 node 可 执行 文件 。 


除 此 之 外 ， 你 可 能 还 需要 执行 以 下 操作 : 


rm -rf /usr/local/bin/npm 

rm -rf /usr/local/share/man/man1/node.1 
rm -rf /usr/local/lib/dtrace/node.d 

rm -rf SUSER/.npm 


2. #ELinux Ei ik Node.js 


本 书 中 在 Linux EEIE Node.js 的 方法 源 自 Stack Overflow 和 GitHub 上 的 相关 指导 。 上 有 具体 
操作 如 下 所 示 。 


(1) 使 用 which node 来 查看 node 的 安装 路 径 。 假 设 该 路 径 为 /usr/local/bin/node。 
(2) 用 cd 命令 切换 到 /usr/local 目录 。 
(3) 执行 以 下 命令 。 


sudo rm -rf bin/node 

sudo rm -rf bin/npm 

sudo rm -rf lib/node modules/npm 
sudo rm -rf lib/node 

sudo rm -rf share/man/*/node.* 











3. ÆWindows E £l; Node.js 
本 书 中 在 Windows EEIE Node.js 的 方法 源 自 Team Treehouse 网 站 中 的 一 篇 文章 。 以 下 是 
具体 的 操作 步骤 。 


(1) 打 开 Windows 的 控制 面板 。 

(2) 选择 “程序 和 功能 ”。 

(3) Rick “HAHET o 

(4) 选择 Node js, Aa tt EIR, 























A.2.4 安装 Yeoman 

Yeoman 由 以 下 部 分 组 成 : 

。 yo， 用 于 快速 搭建 项 目 ， 

。 npnm 或 者 bower ， 用 于 包 管 理 ， 

。 gulp 或 者 grunt， 用 于 构建 系统 。 

在 本 书 的 代码 示例 中 ，gulp 和 grunt-cli 会 用 于 构建 系统 。 虽 然 本 书 的 主要 构建 工具 是 
guLp， 但 有 时 也 需要 grunt-cli 来 执行 一 些 gulp 任务 。 


我 选择 bower 作为 包 管 理工 具 。 



































安装 指南 | 267 


以 下 是 具体 的 安装 步骤 。 
。 安装 yo: 
— npm install -g yo 
— 测试 yo 的 安装 : yo --version 
。 安装 bower: 
— npm install -g bower 
— 测试 bower 的 安装 : bower --version 
。 安装 gulp: 
— npm install -g gulp-cli 
一 测试 gulp 的 安装 : gulp --version 
。 安装 grunt-cli; 
— npm install -g grunt-cli 
— 测试 grunt-cli 的 安装 : grunt --version 
如 需 了 解 更 多 信息 ， 可 参考 Yeoman 的 安装 配置 页 面 。 


安装 Yeoman 生 成 器 generator -webapp 
参考 generator-webapp 的 GitHub 主页 ， 使 用 以 下 方式 来 安装 生成 器 : 


npm install -g generator-webapp 


A.2.5 安装 npm 模 块 
本 书 会 在 命令 行 中 使 用 到 以 下 opm 模块 ， 因 此 我 们 需要 对 它们 进行 全 局 安装 ， 


e jsonlint 




















。 json 

e ujs-jsonvalidate 

。 http-server 

e json-server 

e jq-tutorial 

1. 安装 jsonLint 

该 模块 是 JSONLint 网 站 所 对 应 的 npm 包 ， 用 于 校 验 ISON 文档 。 有 具体 信息 可 参考 其 GitHub 
主页 。 

安装 jsonlint: 


npm install -g jsonlint 


校 验 ISON 文档 : 





jsonlint basic.json 
2. 安装 json 


json 模块 提供 了 在 命令 行 中 处 理 JSON 文档 (如 优化 显示 ) 的 功能 。json 与 3a 类 似 ， 但 
功能 没有 jq 强大 。 
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安装 json: 

npm install -g json 
如 需 了 解 json 的 使 用 信息 ， 可 参考 其 GitHub 主页 。json 能 够 以 npm 包 的 形式 来 使 用 。 
3. 安装 ujs-jsonvalidate 


该 模块 是 ISON Validate 网 站 所 对 应 的 npm 包 ， 用 于 根据 ISON Schema 来 校 验 ISON X 
档 。 具 体 信息 可 参考 其 Github 主页 。 


安装 ujs-jsonvalidate: 








npm install -g ujs-jsonvalidate 
校 验 JSON 文档 : 
validate basic.json basic-schema.json 


4. 安装 http-server 

http-server 是 一 个 简单 的 Web 服务 器 ， 用 于 将 本 机 系统 中 当前 路 径 下 的 文件 以 静态 内 容 
资产 的 形式 向 外 暴露 。 因 为 http-server 文档 齐全 ， 命 令 行 选项 与 关闭 方式 也 完全 符合 直 
觉 ， 所 以 我 很 喜欢 使 用 该 工具 。 具 体 信息 可 参考 其 GitHub 主页 与 npm ER. 


安装 http-server: 





npm install -g http-server 

可 以 使 用 以 下 方式 来 运行 Web 服务 器 : 
http-server -p 8081 

可 以 使 用 以 下 地 址 来 访问 文件 资源 : 
http://localhost:8081 

Rtt Ctrl-C 即 可 关闭 服务 器 。 


5. 安装 json-server 


json-server 是 一 个 模拟 的 REST 服务 器 ， 可 接受 JSON 文件 并 将 其 暴露 为 RESTful 服务 。 
具体 信息 可 参考 其 GitHub 主页 。 











安装 json-server: 
npm install -g json-server 

可 以 使 用 以 下 方式 来 运行 json-server: 
json-server -p 5000 ./speakers.json 

可 以 使 用 以 下 地 址 来 访问 RESTful 资源 : 
http://localhost:5000/speakers 


6. 安装 Crest 
Crest 是 一 个 小 型 的 REST 服务 器 ， 为 MongoDB 数据 库 提 供 了 RESTful 的 封装 层 。 具 体 信 




















息 可 参考 其 GitHub 主页 。 安 装 Crest 的 最 简 方法 本 来 应 该 是 通过 npm 全 局 安装 ， 可 惜 这 条 
路 目前 走 不 通 。 因 此 ， 需 要 采用 git clone 的 方案 ， 具 体操 作 如 下 。 


(1) 用 cd 命令 将 当前 路 径 切换 到 其 他 开发 项 目 所 在 的 目录 下 。 姑 且 称 此 目录 为 projects。 
cd projects 

(2) 克隆 Crest 的 Git 仓库 。 
git clone git://github.com/Cordazar/crest.git 

(3) 切换 到 crest 目录 。 


cd crest 





























(4) 2i #4 config.json X fF, TH Be FE HP AY username 和 password 部 分 信息 。 当 然 ， 这么 
做 是 不 安全 的 ， 你 稍 后 可 以 再 加 上 这 些 字段 信息 ， 并 赋 以 正确 的 值 ， 只 要 确保 其 与 
MongoDB 中 的 密码 一 致 即 可 。 就 目前 而 言 ， 我 们 只 想 快速 上 手 ， 因 此 config.json 文件 
会 如 下 所 示 。 












































{ 
"db": { "port": 27017, "host": "localhost" }, 
"server": ( "port": 3500, "address": "0.0.0.0" }, 
"flavor": "normal", 
"debug": true 

} 


(5) 确保 已 经 安装 并 启动 了 MongoDB, 


(6) 在 一 个 新 的 命令 行 窗口 中 ， 用 node server 命令 来 启动 Crest。 你 应 该 可 以 观察 到 以 下 
结果 。 


node server 





DEBUG: util.js is loaded 
DEBUG: rest.js is loaded 
crest listening at http://:::3500 


ri dE. 


7. X 3€ jq- tutorial 

ja-tutorial 模块 可 以 在 命令 行 中 提供 不 错 的 3a 教程 ， 可 以 用 以 下 方式 对 其 进行 安装 : 
npm install -g jq-tutorial 

安装 后 即 可 在 命令 行 中 运行 该 教程 : 


jq-tutorial 




















A.3 安装 Ruby on Rails 


安装 Ruby on Rails 的 方法 有 很 多 种 : 


* Rails 安装 程序 ， 
e ruby-install; 
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。 Ruby 版 本 管理 器 (Ruby Version Manager, RVM) + rails 包 ; 
e rbenv- rails 包 。 





A.3.1 在 macOS 和 Linux 上 安装 Rails 


我 喜欢 在 macOS 和 Linux 上 使 用 RVM 来 安装 Rails， 因 为 这 种 方式 在 升级 切换 Ruby 版 本 
时 非常 简单 。 可 访问 RVM 的 官方 网 站 ， 并 参考 网 站 上 的 安装 步 又 来 安装 RVM。 


可 以 使 用 RVM 按照 以 下 步骤 来 安装 Ruby, 
(1) 查看 可 安装 的 Ruby 版 本 。 
rvm list known 
(2) 用 以 下 方式 安装 Ruby v2.4.0, 
rvm install 2.4.0 
(3) 检查 已 安装 的 Ruby 版 本 ， 应 该 可 以 观察 到 以 下 结果 。 


ruby -v 
ruby 2.4.0 


(4) 安装 好 Ruby 后 ， 就 可 以 使 用 以 下 方式 来 安装 Rails 了 。 
gem install rails 
(5) 检查 已 安装 的 Rails 版 本 ， 应 该 可 以 观察 到 以 下 结果 。 


rails -v 
Rails Rails 5.0.2 


至 此 ， 安 装 工作 就 算 完成 了 。 
可 以 通过 以 下 步骤 轻松 地 将 Ruby 和 Rails 升级 到 新 版 本 。 
(1) 安装 新 版 本 的 Ruby (以 2x 为 例 )。 
rvm install 2.x 
(2) 使 用 新 版 本 的 Ruby。 
rvm use 2.x 


(3) 与 之 前 一 样 ， 安 装 rails gem, 





























A.3.2 在 Windows 上 安装 Rails 

可 以 在 Windows 环境 下 使 用 Rails 安装 程序 来 安装 Rails， 有 具体 操作 如 下 。 
。 FX Windows 中 的 安装 程序 。 
。 运行 安装 程序 并 使 用 程序 中 的 默认 选项 。 


我 在 Windows 7 环境 下 成 功 使 用 Rails 安装 程序 完成 了 安装 工作 。Rails 安装 程序 的 官方 网 
页 中 包含 了 非常 优秀 的 RoR 教程 ， 以 及 安装 过 程 中 可 能 出 现 的 问题 的 解决 方案 。 
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A.3.3 安装 Ruby gem 
除 Rails 外 ， 本 书 还 使 用 到 了 以 下 Ruby gem， 因 此 我 们 会 以 全 局 方式 对 其 进行 安装 : 


。 multijson 
































。 oj 

e awesome_print 
e activesupport 
e minitest 

e mailcatcher 


1. 安装 multi_json 


multi json 封装 了 gem 的 选择 和 调用 ， 自 动 选 择 当前 应 用 程序 环境 中 最 快 的 JSON 包 。 具 
体 的 安装 过 程 如 下 所 示 : 


gem install multi json 











2. 安装 oj 
很 多 人 认为 Optimized JSON (0j) 是 Ruby 中 最 快 的 JSON 处 理工 具 。 具 体 的 安装 过 程 如 
下 所 示 : 


gem install oj 





3. HAF awesome_print 
awesome print 能 够 以 优化 显示 的 方式 来 打印 Ruby 对 象 ， 可 用 于 调试 过 程 。 有 具体 的 安装 过 
程 如 下 所 示 : 


gem install awesome print 





4. 安装 activesupport 
activesupport 提供 了 从 Rails 中 抽取 出 来 的 一 些 功能 ， 其 ISON 模块 提供 了 在 驼峰 式 命名 
和 下 划 线 分 隔 命 名 间 进 行 转换 的 功能 。 具 体 的 安装 过 程 如 下 所 示 : 


gem install activesupport 

















5. 安装 mailcatcher 
mailcatcher 是 一 个 简单 的 邮件 (SMTP) 服务 器 。 使 用 该 优秀 工具 的 话 ， 无 须发 送 真正 的 
电子 邮件 即 可 完成 对 邮件 功能 的 测试 。 具 体 的 安装 过 程 如 下 所 示 : 


gem install mailcatcher 
A.4 安装 MongoDB 
可 参考 MongoDB 官方 网 站 上 的 安装 文档 ， 根 据 相 应 的 步 又 在 本 机 上 安装 并 运行 MongoDB, 
A. 安装 Java 环 境 


本 书 中 的 Java 环境 包括 以 下 两 部 分 内 容 : 
。 Java SE 
e Gradle 


272 | MA 


























A.5.1 安装 Java SE 

本 书 使 用 Java 标准 版 本 (Standard Edition, SE) 8， 因 此 可 访问 Oracle 网 站 上 Java SE 8 的 
下 载 页 面 。 

还 可 以 在 该 页 面 上 看 到 JDK (Java Developer Kit, Java 开发 者 套件 ) 这 一 术语 。JDK 是 
Java SE 的 旧称 。 只 需要 找到 Java SE Development Kit， 接 受 许 可 证 ， 并 将 文件 下 载 到 本 机 
操作 系统 中 即 可 。 下 载 并 运行 安装 程序 后 ， 需 要 在 操作 系统 中 配置 Java 命令 行 环境 。 

执行 完 操作 系统 需要 的 配置 工作 后 ， 运 行 以 下 命令 : 


java -version 


可 以 观察 到 类 似 以 下 的 结果 : 

java version "1.8.0_72" 

Java(TM) SE Runtime Environment (build 1.8.0_72-b15) 

Java HotSpot(TM) 64-Bit Server VM (build 25.72-b15, mixed mode) 
1. 在 macOS 上 配置 Java 


在 .bashrc 文件 中 使 用 以 下 代码 来 配置 JAVA_HOME 环境 变量 ， 并 将 其 添加 到 PATH 中 : 





























export 
JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk1.x.y.jdk/Contents/Home 
# x 和 y 分 别 为 小 版 本 号 和 补丁 版 本 号 


export PATH=...:$\{JAVA_HOME}/bin:... 


2. 在 Linux 上 配置 Java 
在 .bashrc 文件 中 使 用 以 下 代码 来 配置 JAVA_HOME 环境 变量 ， 并 将 其 添加 到 PATH 中 : 





export JAVA_HOME=/usr/java/jdk1.x.y/bin/java # x 和 y 分 别 为 小 版 本 号 和 补丁 版 本 号 


export PATH=...:$\{JAVA_HOME}/bin:... 
然后 更 新 环境 变量 : 

source ~/.bashrc 
上 述 内 容 源 于 nixCraft 上 的 相关 文章 。 
3. 在 Windows 上 配置 Java 


Java 的 Windows 安装 程序 一 般 会 将 IDK 安装 到 C:\Program Files\Java 或 者 C:\Program Files 
(x86)\Java tf, 


安装 完成 后 ， 执 行 以 下 配置 操作 。 
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() 在 桌面 上 右键 点 击 “ 我 的 电脑 ”， 然 后 选择 “属性 ”。 

(2) 点 击 “高 级 ”选项 。 

(3) 点 击 “ 环 境 变量 ”按钮 。 

(4) 在 “系统 变量 ”下 方 点 击 “ 新 建 ”。 

(5) 输 入 变量 名 为 JAVA_HOME。 

(6) 输入 变量 值 为 刚 安装 的 Java Development Kit 的 路 径 (JDK 安装 目录 )。 
(7) 点击“ 确定 ”。 

(8) 点 击 “ 应 用 ”。 


上 述 内 容 源 于 Robert Sindall 的 一 篇 博客 文章 。 




















A.5.2 ”安装 Gradle 


Gradle 用 于 构建 源 代码 ， 并 测试 代码 。 可 访问 Gradle 的 安装 指南 ， 根 据 文档 上 的 步骤 在 本 
机 操作 系统 中 对 其 进行 安装 。 安 装 完成 后 ， 在 命令 行 中 运行 gradle -v， 应 该 可 以 观察 到 
类 似 以 下 的 结果 : 


gradle -v 
































我 成 功 地 在 macos 上 使 用 过 Homebrew 来 安装 Gradle。 


rm s LT. 
A.6 安装 jq 
jq 是 一 个 命令 行 中 的 ISON 处 理工 具 。 可 根据 ja 在 GitHub 主页 上 的 下 载 指南 文档 来 安装 ja. 


ja 的 运行 依赖 于 cURL。 


A.7 ”安装 cURL 


cURL 可 以 实现 包括 HTTP 在 内 的 多 种 协议 间 的 通信 。 可 以 使 用 cURL 在 命令 行 中 向 
RESTful API 发 起 HTTP 调用 。 





A.7.1 在 macOS 上 安装 CURL 
5 Linux 一 样 ， 你 的 Mac 机 器 中 可 能 已 经 默认 安装 了 cURL。 可 以 使 用 以 下 方式 来 检查 : 
curl --version 


如 果 已 经 安装 cURL， 那 么 你 就 无 须 再 做 任何 其 他 操作 。 否 则 就 需要 手工 来 安装 cURL。 在 
macOS 上 ， 我 将 Homebrew 作为 包 安 装 管理 工具 ， 因 此 可 以 使 用 以 下 命令 来 安装 cURL: 


brew install curl 
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A.7.2 在 Linux 上 安装 CURL 

可 以 使 用 以 下 命令 来 检查 CURL 当前 的 安装 情况 : 
curl --version 

如 尚未 安装 ， 则 可 在 命令 行 中 执行 以 下 命令 : 
sudo apt-get install curl 


该 命令 可 以 成 功 地 在 Ubuntu 或 者 Debian 上 安装 CURL, 





A.7.3 在 Windows 上 安装 cURL 
可 以 通过 以 下 步骤 在 Windows 上 安装 cURL. 


(1) 访问 CURL 的 下 载 页 面 。 

(2) 选择 包 类 型 为 : curl 可 执行 文件 。 

(3) 选择 操作 系统 为 ，Windows/Win32 或 者 Win64。 

(4) 选择 用 户 喜 好 为 ，Cygwin (如 果 使 用 了 Cygwin) 或 者 Generic (如 果 未 使 用 Cygwin)。 
(5) 选择 Win32 的 版 本 (如果 第 3 步 中 选择 了 Windows/Win32) 79: Unspecified. 


上 述 内 容 源 自 Stack Overflow 上 的 相关 讨论 。 


A.8 安装 Apache Kafka 


第 10 章 使 用 了 Apache Kafka 来 实现 ISON 消息 系统 。Kafka 的 运行 依赖 于 Apache ZooKeeper, 
因此 你 还 需要 安装 ZooKeeper。 因 为 Kafka 是 用 Java 开发 的 ， 所 以 在 继续 深入 前 ， 需 要 先 
确保 本 机 上 已 经 安装 好 Java 环境 。 

A.8.1 在 macOS 上 安装 Kafka 

在 macOS 上 安装 Kafka 的 最 简 方 式 是 使 用 Homebrew。 可 在 命令 行 中 运行 以 下 命令 : 


brew install kafka 























该 操作 会 在 机 器 上 安装 Kafka 和 ZooKeeper。 


A.8.2 在 UNIX 上 安装 Kafka 
可 以 通过 以 下 方式 来 安装 ZooKeeper。 
。 从 ZooKeeper 的 发 布 页 面 中 下 载 ZooKeeper。 
。 解压 下 载 的 最 新 ZooKeeper 文件 。 
tar -zxf ZooKeeper-3.4.9.tar.gz 
。 在 ~/.bashrc 文件 中 添加 系统 环境 变量 。 


export ZooKeeper HOME = <Zookeeper-InstaLL-Path>/zookeeper-3.4.9 
export PATH=$PATH: $ZOOKEEPER_HOME/bin 
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可 以 通过 以 下 方式 来 安装 Kafka。 
(1) 从 Kafka 的 下 载 页 面 中 下 载 Kafka。 
(2) 解压 下 载 的 最 新 Kafka 文件 。 
tar -zxf kafka_2.11-0.10.1.1.tgz 
(3) 在 ~/.bashrc 文件 中 添加 系统 环境 变量 。 


export KAFKA HOME = <Kafka-Install-Path>/zookeeper-3.4.9 
export PATH-SPATH:SKAFKA HOME/bin 


BRAZI Á TutorialsPoint 网 站 上 的 相关 文章 。 


























A.8.3 在 Windows 上 安装 Kafka 
可 以 通过 以 下 方式 来 安装 ZooKeeper。 
(1) 从 ZooKeeper 的 下 载 页 面 中 下 载 ZooKeeper。 
(2) 使 用 喜欢 的 解压 工具 将 ZooKeeper 解压 到 C 盘 。 
(3) 使 用 以 下 方式 添加 系统 环境 变量 。 
a. Æ Windows 中 ， 打 开 控 制 面板 一 系统 一 高 级 系统 设置 一 环境 变量 。 
b. 对 于 最 新 下 载 的 ZooKeeper， 创 建新 的 系统 环境 变量 
ZOOKEEPER HOME = C:\zookeeper-3.4.9 
c. 将 ZooKeeper 添加 到 PATH 环境 变量 中 ， 具 体操 作 方 式 为 :编辑 PATH 并 在 其 最 后 添加 
以 下 后 级 。 
;%ZOOKEEPER_HOME%\bin; 
可 以 通过 以 下 方式 来 安装 Kafka。 
(1) 从 Kafka 的 下 载 页 面 中 下 载 Kafka。 
(2) 使 用 喜欢 的 解压 工具 将 Kafka 解压 到 C 盘 。 
(3) 使 用 以 下 方式 添加 系统 环境 变量 。 
a. 在 Windows 中 ， 打 开 控 制 面板 一 系统 一 高 级 系统 设置 一 环境 变量 。 
b. 对 于 最 新 下 载 的 Kafka， 创 建新 的 系统 环境 变量 。 


KAFKA HOME = C:\kafka_2.11-0.10.1.1 


c. 将 Kafka 添加 到 PATH 环境 变量 中 ， 具 体操 作 方 式 为 : 编辑 PATH 并 在 其 最 后 添加 以 下 
Ja. 
3%KAFKA_HOME%\ bin; 


上 述 内 容 源 自 DZone 网 站 上 的 相关 文章 。 


A.9 内 容 参考 
本 附录 的 AsciiDoc 版 本 是 由 Pandoc 根据 本 书 GitHub 上 的 Markdown 文章 所 生成 的 。 
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HRB 
JSON 社 区 





JSON 社区 非常 活跃 。 你 可 以 访问 以 下 群 组 、 参 与 社区 并 进一步 学 习 。 
JSON.org 
Douglas Crockford 创立 的 JSON 网 站 ， 即 JSON 的 起 源 。 
JSON Yahoo! 群 组 
该 Yahoo! 群 组 从 属于 JSON.org 网 站 。 
json-ietf 邮件 列表 
维护 JSON IETF 标准 的 ISON IETF 工作 组 会 使 用 该 邮件 列表 来 进行 沟通 。 


JSONauts 
另 一 个 优秀 站 点 ， 包 含 JSON 教程 、 工 具 和 文章 。 
JSON Schema 标准 工作 组 





JSON Schema 标准 在 GitHub 上 进行 维护 。 


Google 群 组 : JSON Schema 
该 Google 群 组 与 JSON Schema 标准 工作 组 相关 联 。 


Google 群 组 : api-craft 
该 群 组 关注 API 的 设计 与 开发 。 
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关于 作者 


Tom Marrs 热衷 于 展示 技术 在 商业 上 的 价值 。 作 为 TEKsystems 全 球 服务 部 门 的 企业 架构 
师 ， 他 促使 公司 采用 了 多 项 新 的 API 架构 与 技术 一 一 REST、 微 服务 和 ISON, Tom 领导 过 
各 种 企业 级 的 API、Web、 移 动 端 、 云 和 SOA 项 目 。 作 为 敏捷 开发 的 拥有 至 ，Tom 获得 了 
Scrum 联盟 的 CSM 认证 ， 他 也 乐于 对 项 目 团队 进行 相关 的 辅导 与 训练 。 


除 本 书 外 ，Tom 还 为 DZone 编写 过 (2013 年 年 度 下 载 量 第 一 的 ) JSON 核心 参考 卡片 。 
Tom 与 其 他 人 合作 出 版 过 JBoss at Work (O'Reilly 出 版 社 ) ; 他 还 在 以 下 会 议 上 发 表 过 
i 讲 : O'Reilly Open Source Convention (OSCON), No Fluff Just Stuff (NFJS) 和 Great 
Indian Developer Summit (GIDS), Tom 希望 不 久 的 将 来 能 够 继续 在 这 些 会 议 上 进行 分 享 


关于 封面 


本 书 封面 上 的 动物 是 一 只 西伯 利 亚 松 臣 (Perisoreus infaustus)， 这 是 一 种 栖息 于 欧 亚 大 陆 
北部 的 小 型 岛 类 。 它 们 的 栖息 范围 极其 广阔 : 西 至 瑞典 ， 东 至 中 国 。 它 们 会 在 北方 密集 的 
针 叶 林 中 筑 集 。 

西伯 利 亚 松 鸦 最 长 可 达 29 厘米 ， 重 至 79 克 。 它 们 有 着 长 长 的 尾巴 和 棕 灰色 的 外 表 。 这 种 
GRARPEMN, URRAHTFAR, ANMARARR, BAUR DREAM, H 
鸟 会 在 每 年 的 三 四 月 间 产 卵 ， 并 在 冬季 来 临 前 抚育 幼 仔 。 

证 据 表 明 ， 由 于 人 类 对 森林 的 砍伐 ， 欧 洲 地 区 的 西伯 利 亚 松 鸦 的 数量 正在 日 益 减 少 。 不 
过 ， 因 为 该 物种 在 亚洲 地 区 广泛 而 又 稀 跌 地 分 布 ， 所 以 西伯 利 亚 松 臣 目前 尚未 列 入 濒危 动 
物 的 名 单 中 。 

O'Reilly 封面 上 的 许多 动物 都 已 濒临 灭绝 ， 但 它们 的 存在 对 世界 至 关 重 要 。 想 要 了 解 如 何 
帮助 它们 ， 可 以 登录 animals.oreilly.com, 

本 书 封面 的 图 片 来 自 Riverside Natural History 一 书 。 








278 


To 


微 信 连 接 





回复 “JSON” 查 看 相关 书 单 


3 
微 博 连 接 
关注 @ 图 灵 教 育 每 日 分 享 上 T 好 书 


e 
QQ 连接 


图 灵 读 者 官方 群 I: 218139230 
图 灵 读 者 官方 群 I[: 164939616 














图 灵 社 区 
iTuring.cn 
在 线 出 版 , 电子 书 ,《 码 农 》 杂 志 , 图 灵 访 谈 














OREILLY 





JSON 实 战 


JSON 已 经 成 为 RESTful 接 口 设计 的 事实 标准 ， 并 在 互联 网 数据 交换 领域 
日 益 受 亲 睐 ， 是 搭建 优雅 、 高 效应 用 程序 的 得 力 工具 。 


本 书 系统 展示 如 何 使 用 JSON 工 具 和 消息 /文档 设计 来 搭建 企业 级 应 用 程 
序 与 服务 ， 既 包括 JSON 基 础 知识 ， 又 涵盖 大 量 操作 实践 与 使 用 案例 ， 是 
全 面 掌握 JSON 强 大 功能 的 明智 之 选 。 


m 熟悉 JSON 基 础 知识 并 学 习 如 何 对 JSON 数 据 进行 建 模 

m 学 习 如 何在 Node.js、Ruby on Rails 以 及 Java 中 使 用 JSON 
m 使 用 JSON Schema 构建 JSON 文 档 来 设计 并 测试 API 

m 使 用 JSON 搜 索 工 具 来 搜索 JSON 文 档 的 内 容 

m 使 用 JSON 转 换 工具 将 JSON 文 档 转换 成 其 他 数据 格式 

E 比较 HAL 和 jsonapi 等 JSON 超 媒体 格式 

m 使 用 MongoDB 来 存储 和 处 理 JSON 文 档 

m 使 用 Apache Kafka 在 服务 间 交 换 JSON 消 息 


汤姆 "马尔 斯 (Tom Marrs)， 拥 有 多 年 企业 架构 经 验 ， 领 导 过 各 种 企业 级 
的 API、Web、 移 动 端 、 云 和 SOA 项 目 。 目 前 任 TEKsystems 全 球 服务 部 
门 企业 架构 师 ， 促 使 公司 采用 了 包括 REST、 微 服务 和 JSON 在 内 的 多 项 
APl 架 构 与 技术 。Tom 还 是 敏捷 开发 的 拥 利 ， 并 获得 Scrum 联 盟 的 CSM 
认证 。 
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看 完了 


如 果 您 对 本 书 内 容 有 疑问 ， 可 发 邮件 至 contact@turingbook.com， 会 有 编辑 
或 作 译 者 协助 答疑 。 也 可 访问 图 灵 社 区 ， 参 与 本 书 讨 论 。 


如 果 是 有 关 电 子 书 的 建议 或 问题 ， 请 联系 专用 客服 邮箱 : 


ebook@turingbook.com, 
在 这 可 以 找到 我 们 : 


微 博 @ 图 灵 教育 : 好 书 、 活 动 每 日 播报 

微 博 @ 图 灵 社 区 : 电子 书 和 好 文章 的 消息 

微 博 @ 图 灵 新 知 : 图 灵 教 育 的 科普 小 组 

Mis 图 灵 访 谈 : ituring_interview， 讲 述 码 农 精彩 人 生 
微 信 图 灵 教 育 : turingbooks 


